From 6b52660c66034eeea63b073b6f7422f05264cb37 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sat, 11 Apr 2026 15:25:13 +0000 Subject: [PATCH] chore(i18n): refresh ar translations --- docs/ar/gateway/configuration-reference.md | 2573 +++++++++++------ .../gpt54-codex-agentic-parity-maintainers.md | 174 ++ docs/ar/help/gpt54-codex-agentic-parity.md | 229 ++ docs/ar/plugins/architecture.md | 1777 ++++++------ docs/ar/plugins/manifest.md | 522 ++-- docs/ar/reference/rich-output-protocol.md | 60 + docs/ar/tools/video-generation.md | 358 +-- 7 files changed, 3631 insertions(+), 2062 deletions(-) create mode 100644 docs/ar/help/gpt54-codex-agentic-parity-maintainers.md create mode 100644 docs/ar/help/gpt54-codex-agentic-parity.md create mode 100644 docs/ar/reference/rich-output-protocol.md diff --git a/docs/ar/gateway/configuration-reference.md b/docs/ar/gateway/configuration-reference.md index 2afa4fad1..0e4fc0352 100644 --- a/docs/ar/gateway/configuration-reference.md +++ b/docs/ar/gateway/configuration-reference.md @@ -1,70 +1,70 @@ --- read_when: - - تحتاج إلى دلالات الإعدادات الدقيقة على مستوى الحقول أو القيم الافتراضية - - أنت تتحقق من كتل إعدادات القناة أو النموذج أو البوابة أو الأداة + - تحتاج إلى دلالات الإعدادات الدقيقة على مستوى الحقول أو إلى القيم الافتراضية. + - أنت تتحقق من صحة كتل إعدادات القناة أو النموذج أو البوابة أو الأداة. summary: مرجع إعدادات البوابة لمفاتيح OpenClaw الأساسية، والقيم الافتراضية، وروابط إلى مراجع الأنظمة الفرعية المخصصة title: مرجع الإعدادات x-i18n: - generated_at: "2026-04-11T02:44:27Z" + generated_at: "2026-04-11T15:16:02Z" model: gpt-5.4 provider: openai - source_hash: 32acb82e756e4740d13ef12277842081f4c90df7b67850c34f8a76701fcd37d0 + source_hash: 351a245bed59d852ea8582e4e9fec5017a5c623cd6f0034766cdea1b5330be3c source_path: gateway/configuration-reference.md workflow: 15 --- # مرجع الإعدادات -مرجع الإعدادات الأساسية لملف `~/.openclaw/openclaw.json`. للحصول على نظرة عامة موجّهة حسب المهام، راجع [الإعدادات](/ar/gateway/configuration). +مرجع الإعدادات الأساسية لملف `~/.openclaw/openclaw.json`. للحصول على نظرة عامة موجهة حسب المهام، راجع [الإعدادات](/ar/gateway/configuration). -تغطي هذه الصفحة أسطح إعدادات OpenClaw الرئيسية، وتضع روابط خارجية عندما يكون لأحد الأنظمة الفرعية مرجع أعمق خاص به. وهي **لا** تحاول تضمين كل فهرس أوامر مملوك للقنوات/الـ plugins أو كل إعدادات الذاكرة/QMD العميقة في صفحة واحدة. +تغطي هذه الصفحة أسطح إعدادات OpenClaw الرئيسية، وتوفّر روابط خارجية عندما يكون لنظام فرعي مرجع أعمق خاص به. وهي **لا** تحاول تضمين كل فهرس أوامر مملوك للقنوات/الـ plugin أو كل إعداد دقيق متعلق بالذاكرة/QMD في صفحة واحدة. -مصدر الحقيقة في الشيفرة: +مرجع الشيفرة: -- يطبع `openclaw config schema` مخطط JSON Schema الحي المستخدم للتحقق وواجهة Control UI، مع دمج بيانات التعريف الخاصة بالحزم المضمّنة/الـ plugins/القنوات عند توفرها -- يعيد `config.schema.lookup` عقدة مخطط واحدة محددة بالمسار لأدوات الاستكشاف التفصيلي -- يتحقق `pnpm config:docs:check` / `pnpm config:docs:gen` من تجزئة خط الأساس لوثائق الإعدادات مقابل سطح المخطط الحالي +- يعرض `openclaw config schema` مخطط JSON المباشر المستخدم للتحقق وواجهة Control UI، مع دمج بيانات التعريف الخاصة بالحِزم المضمنة/الـ plugin/القنوات عند توفرها +- يعيد `config.schema.lookup` عقدة مخطط واحدة محددة النطاق للمسار لأدوات الاستكشاف التفصيلي +- يتحقق `pnpm config:docs:check` / `pnpm config:docs:gen` من تجزئة خط أساس توثيق الإعدادات مقابل سطح المخطط الحالي -مراجع عميقة مخصصة: +مراجع معمقة مخصصة: -- [مرجع إعدادات الذاكرة](/ar/reference/memory-config) من أجل `agents.defaults.memorySearch.*` و`memory.qmd.*` و`memory.citations` وإعدادات dreaming تحت `plugins.entries.memory-core.config.dreaming` -- [Slash Commands](/ar/tools/slash-commands) من أجل فهرس الأوامر الحالي المضمّن + المجمّع -- صفحات القنوات/الـ plugins المالكة لأسطح الأوامر الخاصة بالقنوات +- [مرجع إعدادات الذاكرة](/ar/reference/memory-config) لـ `agents.defaults.memorySearch.*` و`memory.qmd.*` و`memory.citations` وإعدادات dreaming ضمن `plugins.entries.memory-core.config.dreaming` +- [Slash Commands](/ar/tools/slash-commands) لفهرس الأوامر الحالي المضمّن + المجمّع +- صفحات القنوات/الـ plugin المالكة لأسطح الأوامر الخاصة بالقنوات -تنسيق الإعدادات هو **JSON5** (يُسمح بالتعليقات والفواصل الختامية). جميع الحقول اختيارية — يستخدم OpenClaw قيمًا افتراضية آمنة عند حذفها. +تنسيق الإعدادات هو **JSON5** (يُسمح بالتعليقات والفواصل اللاحقة). جميع الحقول اختيارية — يستخدم OpenClaw قيماً افتراضية آمنة عند عدم تحديدها. --- ## القنوات -تبدأ كل قناة تلقائيًا عندما يكون قسم إعداداتها موجودًا (إلا إذا كان `enabled: false`). +تبدأ كل قناة تلقائياً عند وجود قسم إعداداتها (ما لم يكن `enabled: false`). ### الوصول إلى الرسائل الخاصة والمجموعات تدعم جميع القنوات سياسات الرسائل الخاصة وسياسات المجموعات: | سياسة الرسائل الخاصة | السلوك | -| -------------------- | ------- | -| `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 { @@ -85,9 +85,9 @@ x-i18n: } ``` -### القيم الافتراضية للقنوات والنبض +### القيم الافتراضية للقنوات وإشارة النبض -استخدم `channels.defaults` من أجل سلوك سياسة المجموعات والنبض المشترك بين الموفرين: +استخدم `channels.defaults` للسلوك المشترك الخاص بسياسة المجموعات وإشارة النبض عبر الموفرين: ```json5 { @@ -105,15 +105,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 { @@ -146,7 +146,7 @@ x-i18n: } ``` - + ```json5 { @@ -164,10 +164,10 @@ x-i18n: } ``` -- تستخدم الأوامر الصادرة الحساب `default` افتراضيًا إذا كان موجودًا؛ وإلا فسيُستخدم أول معرّف حساب مُعدّ (بعد الفرز). -- يتيح `channels.whatsapp.defaultAccount` الاختياري تجاوز اختيار الحساب الافتراضي الاحتياطي عندما يطابق معرّف حساب مُعدّ. -- يقوم `openclaw doctor` بترحيل دليل مصادقة Baileys القديم ذي الحساب الواحد إلى `whatsapp/default`. -- تجاوزات لكل حساب: `channels.whatsapp.accounts..sendReadReceipts` و`channels.whatsapp.accounts..dmPolicy` و`channels.whatsapp.accounts..allowFrom`. +- تستخدم الأوامر الصادرة الحساب `default` افتراضياً إذا كان موجوداً؛ وإلا يُستخدم أول معرّف حساب مُعدّ (بعد الترتيب). +- يجاوز `channels.whatsapp.defaultAccount` الاختياري هذا الاختيار الافتراضي الاحتياطي للحساب عندما يطابق معرّف حساب مُعدّ. +- يُرحّل `openclaw doctor` دليل مصادقة Baileys القديم ذي الحساب الواحد إلى `whatsapp/default`. +- التجاوزات لكل حساب: `channels.whatsapp.accounts..sendReadReceipts` و`channels.whatsapp.accounts..dmPolicy` و`channels.whatsapp.accounts..allowFrom`. @@ -225,12 +225,12 @@ x-i18n: } ``` -- رمز البوت: `channels.telegram.botToken` أو `channels.telegram.tokenFile` (ملف عادي فقط؛ تُرفض الروابط الرمزية)، مع استخدام `TELEGRAM_BOT_TOKEN` كخيار احتياطي للحساب الافتراضي. -- يتيح `channels.telegram.defaultAccount` الاختياري تجاوز اختيار الحساب الافتراضي عندما يطابق معرّف حساب مُعدّ. -- في إعدادات الحسابات المتعددة (وجود معرفي حسابات أو أكثر)، عيّن قيمة افتراضية صريحة (`channels.telegram.defaultAccount` أو `channels.telegram.accounts.default`) لتجنب التوجيه الاحتياطي؛ ويحذّر `openclaw doctor` عندما تكون هذه القيمة مفقودة أو غير صالحة. -- يحظر `configWrites: false` عمليات كتابة الإعدادات التي يبدأها Telegram (ترحيل معرّفات المجموعات الفائقة، وأوامر `/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.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 Agents](/ar/tools/acp-agents#channel-specific-settings). +- تستخدم معاينات البث في Telegram `sendMessage` + `editMessageText` (وتعمل في المحادثات المباشرة والجماعية). - سياسة إعادة المحاولة: راجع [سياسة إعادة المحاولة](/ar/concepts/retry). ### Discord @@ -333,36 +333,36 @@ x-i18n: } ``` -- الرمز المميز: `channels.discord.token`، مع استخدام `DISCORD_BOT_TOKEN` كخيار احتياطي للحساب الافتراضي. -- تستخدم الاستدعاءات الصادرة المباشرة التي توفّر `token` خاصًا بـ Discord ذلك الرمز المميز لهذا الاستدعاء؛ بينما تظل إعدادات إعادة المحاولة/السياسة الخاصة بالحساب مستمدة من الحساب المحدد في اللقطة النشطة لوقت التشغيل. -- يتيح `channels.discord.defaultAccount` الاختياري تجاوز اختيار الحساب الافتراضي عندما يطابق معرّف حساب مُعدّ. -- استخدم `user:` (رسالة خاصة) أو `channel:` (قناة guild) كأهداف للتسليم؛ تُرفض المعرّفات الرقمية المجردة. -- تكون الأسماء المختصرة للـ guilds بأحرف صغيرة مع استبدال المسافات بـ `-`؛ وتستخدم مفاتيح القنوات الاسم المختصر (من دون `#`). يُفضَّل استخدام معرّفات 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 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` عند حذفها. - - `agentFilter`: قائمة سماح اختيارية لمعرّفات الوكلاء. احذفها لتمرير الموافقات لجميع الوكلاء. - - `sessionFilter`: أنماط اختيارية لمفاتيح الجلسات (تطابق جزئي أو regex). - - `target`: مكان إرسال مطالبات الموافقة. يرسل `"dm"` (الافتراضي) إلى الرسائل الخاصة للمعتمدين، ويرسل `"channel"` إلى القناة الأصلية، ويرسل `"both"` إلى الاثنين معًا. عندما يتضمن الهدف `"channel"`، لا تكون الأزرار قابلة للاستخدام إلا من قبل المعتمدين الذين تم حلهم. - - `cleanupAfterResolve`: عند تعيينها إلى `true`، تحذف الرسائل الخاصة الخاصة بالموافقات بعد الموافقة أو الرفض أو انتهاء المهلة. +- الرمز المميز: `channels.discord.token`، مع `DISCORD_BOT_TOKEN` كخيار احتياطي للحساب الافتراضي. +- تستخدم الاستدعاءات الصادرة المباشرة التي توفّر `token` خاصاً بـ Discord بشكل صريح ذلك الرمز المميز لهذا الاستدعاء؛ بينما تبقى إعدادات إعادة المحاولة/السياسة الخاصة بالحساب مأخوذة من الحساب المحدد في اللقطة النشطة لوقت التشغيل. +- يجاوز `channels.discord.defaultAccount` الاختياري اختيار الحساب الافتراضي عندما يطابق معرّف حساب مُعدّ. +- استخدم `user:` (رسالة خاصة) أو `channel:` (قناة خادم guild) كأهداف للتسليم؛ وتُرفض المعرّفات الرقمية المجردة. +- تكون الأسماء المختصرة لـ guild بأحرف صغيرة مع استبدال المسافات بـ `-`؛ وتستخدم مفاتيح القنوات الاسم المختصر (من دون `#`). يُفضَّل استخدام معرّفات guild. +- تُتجاهل الرسائل التي ينشئها البوت افتراضياً. يفعّل `allowBots: true` قبولها؛ واستخدم `allowBots: "mentions"` لقبول رسائل البوت التي تذكر البوت فقط (مع استمرار تصفية رسائل البوت نفسه). +- يؤدي `channels.discord.guilds..ignoreOtherMentions` (وتجاوزات القنوات) إلى إسقاط الرسائل التي تذكر مستخدماً آخر أو دوراً آخر لكن لا تذكر البوت (باستثناء @everyone/@here). +- يقسم `maxLinesPerMessage` (الافتراضي 17) الرسائل الطويلة عمودياً حتى عندما تكون أقل من 2000 حرف. +- يتحكم `channels.discord.threadBindings` في التوجيه المرتبط بخيوط Discord: + - `enabled`: تجاوز Discord لميزات الجلسات المرتبطة بالخيوط (`/focus` و`/unfocus` و`/agents` و`/session idle` و`/session max-age`، والتسليم/التوجيه المرتبط) + - `idleHours`: تجاوز Discord لإلغاء التركيز التلقائي بعد عدم النشاط بالساعات (`0` يعطّل ذلك) + - `maxAgeHours`: تجاوز Discord للحد الأقصى الصارم للعمر بالساعات (`0` يعطّل ذلك) + - `spawnSubagentSessions`: مفتاح تفعيل اختياري لإنشاء/ربط الخيوط تلقائياً عبر `sessions_spawn({ thread: true })` +- تُعدّ إدخالات `bindings[]` ذات المستوى الأعلى مع `type: "acp"` إعداداً لارتباطات ACP الدائمة للقنوات والخيوط (استخدم معرّف القناة/الخيط في `match.peer.id`). دلالات الحقول مشتركة في [ACP Agents](/ar/tools/acp-agents#channel-specific-settings). +- يضبط `channels.discord.ui.components.accentColor` لون التمييز لحاويات Discord 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` عند عدم تحديده. + - `agentFilter`: قائمة سماح اختيارية لمعرّفات الوكلاء. احذفه لتمرير الموافقات لجميع الوكلاء. + - `sessionFilter`: أنماط مفاتيح الجلسات الاختيارية (سلسلة فرعية أو regex). + - `target`: مكان إرسال مطالبات الموافقة. يرسل `"dm"` (الافتراضي) إلى الرسائل الخاصة للموافق، ويرسل `"channel"` إلى القناة الأصلية، ويرسل `"both"` إلى الاثنين معاً. عندما يتضمن الهدف `"channel"`، لا يمكن استخدام الأزرار إلا من قبل الموافقين الذين تم التعرف عليهم. + - `cleanupAfterResolve`: عندما تكون قيمته `true`، يحذف رسائل الموافقة الخاصة بعد الموافقة أو الرفض أو انتهاء المهلة. -**أوضاع إشعارات التفاعل:** `off` (بدون)، `own` (رسائل البوت، الافتراضي)، `all` (كل الرسائل)، `allowlist` (من `guilds..users` على جميع الرسائل). +**أوضاع إشعارات التفاعلات:** `off` (لا شيء)، `own` (رسائل البوت، افتراضي)، `all` (كل الرسائل)، `allowlist` (من `guilds..users` على جميع الرسائل). ### Google Chat @@ -393,11 +393,11 @@ x-i18n: } ``` -- JSON لحساب الخدمة: مضمن (`serviceAccount`) أو قائم على ملف (`serviceAccountFile`). -- كما أن SecretRef لحساب الخدمة مدعوم أيضًا (`serviceAccountRef`). -- المتغيرات الاحتياطية للبيئة: `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` تفعيل مطابقة مبدأ البريد الإلكتروني القابلة للتغيير (وضع توافق طارئ). ### Slack @@ -464,35 +464,35 @@ 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 حقول مصدر/حالة لكل بيانات الاعتماد مثل +- تقبل `botToken` و`appToken` و`signingSecret` و`userToken` سلاسل نصية صريحة + أو كائنات SecretRef. +- تعرض لقطات حساب Slack حقولاً لكل اعتماد تتعلق بالمصدر/الحالة مثل `botTokenSource` و`botTokenStatus` و`appTokenStatus`، وفي وضع HTTP، `signingSecretStatus`. وتعني `configured_unavailable` أن الحساب مُعدّ عبر SecretRef لكن مسار الأمر/وقت التشغيل الحالي لم يتمكن من حل قيمة السر. -- يحظر `configWrites: false` عمليات كتابة الإعدادات التي يبدأها Slack. -- يتيح `channels.slack.defaultAccount` الاختياري تجاوز اختيار الحساب الافتراضي عندما يطابق معرّف حساب مُعدّ. -- يُعد `channels.slack.streaming.mode` مفتاح وضع بث Slack القياسي. ويتحكم `channels.slack.streaming.nativeTransport` في ناقل البث الأصلي لـ Slack. ويتم ترحيل `streamMode` القديم، وقيم `streaming` المنطقية، و`nativeStreaming` تلقائيًا. +- يمنع `configWrites: false` عمليات كتابة الإعدادات التي تبدأ من Slack. +- يجاوز `channels.slack.defaultAccount` الاختياري اختيار الحساب الافتراضي عندما يطابق معرّف حساب مُعدّ. +- يُعدّ `channels.slack.streaming.mode` مفتاح وضع بث Slack القياسي. ويتحكم `channels.slack.streaming.nativeTransport` في ناقل البث الأصلي لـ Slack. وتُرحَّل تلقائياً القيم القديمة `streamMode` وقيم `streaming` المنطقية و`nativeStreaming`. - استخدم `user:` (رسالة خاصة) أو `channel:` كأهداف للتسليم. -**أوضاع إشعارات التفاعل:** `off` و`own` (الافتراضي) و`all` و`allowlist` (من `reactionAllowlist`). +**أوضاع إشعارات التفاعلات:** `off` و`own` (الافتراضي) و`all` و`allowlist` (من `reactionAllowlist`). -**عزل جلسات السلاسل:** تكون `thread.historyScope` لكل سلسلة على حدة (الافتراضي) أو مشتركة عبر القناة. يقوم `thread.inheritParent` بنسخ سجل القناة الأصلية إلى السلاسل الجديدة. +**عزل جلسات الخيوط:** يكون `thread.historyScope` لكل خيط على حدة (الافتراضي) أو مشتركاً عبر القناة. ويؤدي `thread.inheritParent` إلى نسخ سجل القناة الأصلية إلى الخيوط الجديدة. -- يتطلب البث الأصلي في Slack مع حالة السلسلة بأسلوب المساعد "is typing..." هدف رد ضمن سلسلة. تظل الرسائل الخاصة ذات المستوى الأعلى خارج السلاسل افتراضيًا، ولذلك تستخدم `typingReaction` أو التسليم العادي بدلًا من المعاينة بأسلوب السلسلة. -- تضيف `typingReaction` تفاعلًا مؤقتًا إلى رسالة Slack الواردة أثناء تشغيل الرد، ثم تزيله عند الاكتمال. استخدم الرمز المختصر لإيموجي Slack مثل `"hourglass_flowing_sand"`. -- `channels.slack.execApprovals`: تسليم موافقات exec الأصلية في Slack وتخويل المعتمدين. نفس مخطط Discord: `enabled` (`true`/`false`/`"auto"`)، و`approvers` (معرّفات مستخدمي Slack)، و`agentFilter`، و`sessionFilter`، و`target` (`"dm"` أو `"channel"` أو `"both"`). +- يتطلب البث الأصلي في Slack بالإضافة إلى حالة الخيط بأسلوب "is typing..." الخاصة بمساعد Slack هدف رد ضمن خيط. تبقى الرسائل الخاصة ذات المستوى الأعلى خارج الخيوط افتراضياً، لذلك تستخدم `typingReaction` أو التسليم العادي بدلاً من المعاينة بأسلوب الخيط. +- تضيف `typingReaction` تفاعلاً مؤقتاً إلى رسالة Slack الواردة أثناء تنفيذ الرد، ثم تزيله عند الاكتمال. استخدم shortcode لرمز تعبيري في Slack مثل `"hourglass_flowing_sand"`. +- `channels.slack.execApprovals`: تسليم موافقات exec الأصلية في Slack وتفويض الموافقين. نفس مخطط Discord: `enabled` (`true`/`false`/`"auto"`) و`approvers` (معرّفات مستخدمي Slack) و`agentFilter` و`sessionFilter` و`target` (`"dm"` أو `"channel"` أو `"both"`). | مجموعة الإجراءات | الافتراضي | ملاحظات | -| ---------------- | --------- | ------- | -| reactions | مفعّل | التفاعل + إدراج التفاعلات | -| messages | مفعّل | قراءة/إرسال/تحرير/حذف | -| pins | مفعّل | تثبيت/إزالة تثبيت/إدراج | -| memberInfo | مفعّل | معلومات العضو | -| emojiList | مفعّل | قائمة الإيموجي المخصص | +| ------------ | ------- | ---------------------- | +| reactions | مفعّل | التفاعل + سرد التفاعلات | +| messages | مفعّل | قراءة/إرسال/تعديل/حذف | +| pins | مفعّل | تثبيت/إلغاء تثبيت/سرد | +| memberInfo | مفعّل | معلومات العضو | +| emojiList | مفعّل | قائمة الرموز التعبيرية المخصصة | ### Mattermost @@ -526,23 +526,23 @@ x-i18n: } ``` -أوضاع الدردشة: `oncall` (الرد عند @-mention، وهو الافتراضي)، و`onmessage` (كل رسالة)، و`onchar` (الرسائل التي تبدأ ببادئة تشغيل). +أوضاع الدردشة: `oncall` (الرد عند @-mention، افتراضي)، و`onmessage` (كل رسالة)، و`onchar` (الرسائل التي تبدأ ببادئة تشغيل). عند تفعيل الأوامر الأصلية في 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. +- تتم مصادقة استدعاءات slash الأصلية باستخدام الرموز المميزة الخاصة بكل أمر التي + يعيدها Mattermost أثناء تسجيل أوامر slash. إذا فشل التسجيل أو لم يتم + تفعيل أي أوامر، يرفض OpenClaw الاستدعاءات مع `Unauthorized: invalid command token.` -- بالنسبة إلى مضيفي الاستدعاء العكسي الخاصين/الداخليين/tailnet، قد يتطلب Mattermost - أن تتضمن `ServiceSettings.AllowedUntrustedInternalConnections` المضيف/النطاق الخاص بالاستدعاء العكسي. +- بالنسبة إلى مضيفي الاستدعاء private/tailnet/internal، قد يتطلب Mattermost + أن تتضمن `ServiceSettings.AllowedUntrustedInternalConnections` المضيف/النطاق الخاص بالاستدعاء. استخدم قيم المضيف/النطاق، وليس عناوين URL كاملة. -- يتيح `channels.mattermost.configWrites` السماح أو المنع لعمليات كتابة الإعدادات التي يبدأها Mattermost. -- يفرض `channels.mattermost.requireMention` وجود `@mention` قبل الرد في القنوات. -- يوفر `channels.mattermost.groups..requireMention` تجاوزًا لكل قناة لشرط الإشارة (`"*"` للافتراضي). -- يتيح `channels.mattermost.defaultAccount` الاختياري تجاوز اختيار الحساب الافتراضي عندما يطابق معرّف حساب مُعدّ. +- يتحكم `channels.mattermost.configWrites` في السماح أو منع عمليات كتابة الإعدادات التي تبدأ من Mattermost. +- يتطلب `channels.mattermost.requireMention` وجود `@mention` قبل الرد في القنوات. +- `channels.mattermost.groups..requireMention`: تجاوز اشتراط الإشارة لكل قناة (`"*"` للقيمة الافتراضية). +- يجاوز `channels.mattermost.defaultAccount` الاختياري اختيار الحساب الافتراضي عندما يطابق معرّف حساب مُعدّ. ### Signal @@ -563,15 +563,15 @@ x-i18n: } ``` -**أوضاع إشعارات التفاعل:** `off` و`own` (الافتراضي) و`all` و`allowlist` (من `reactionAllowlist`). +**أوضاع إشعارات التفاعلات:** `off` و`own` (الافتراضي) و`all` و`allowlist` (من `reactionAllowlist`). -- `channels.signal.account`: يثبت بدء تشغيل القناة على هوية حساب Signal محددة. -- `channels.signal.configWrites`: يسمح أو يمنع عمليات كتابة الإعدادات التي يبدأها Signal. -- يتيح `channels.signal.defaultAccount` الاختياري تجاوز اختيار الحساب الافتراضي عندما يطابق معرّف حساب مُعدّ. +- `channels.signal.account`: تثبيت بدء تشغيل القناة على هوية حساب Signal محددة. +- `channels.signal.configWrites`: السماح أو منع عمليات كتابة الإعدادات التي تبدأ من Signal. +- يجاوز `channels.signal.defaultAccount` الاختياري اختيار الحساب الافتراضي عندما يطابق معرّف حساب مُعدّ. ### BlueBubbles -يُعد BlueBubbles المسار الموصى به لـ iMessage (مدعومًا عبر plugin، ويُضبط تحت `channels.bluebubbles`). +يُعد BlueBubbles المسار الموصى به لـ iMessage (مدعوماً عبر plugin، ويُعد ضمن `channels.bluebubbles`). ```json5 { @@ -586,14 +586,14 @@ x-i18n: } ``` -- مسارات المفاتيح الأساسية المغطاة هنا: `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). +- مسارات المفاتيح الأساسية المغطاة هنا: `channels.bluebubbles`، و`channels.bluebubbles.dmPolicy`. +- يجاوز `channels.bluebubbles.defaultAccount` الاختياري اختيار الحساب الافتراضي عندما يطابق معرّف حساب مُعدّ. +- يمكن لإدخالات `bindings[]` ذات المستوى الأعلى مع `type: "acp"` ربط محادثات BlueBubbles بجلسات ACP دائمة. استخدم مقبض BlueBubbles أو سلسلة الهدف (`chat_id:*` أو `chat_guid:*` أو `chat_identifier:*`) في `match.peer.id`. دلالات الحقول المشتركة: [ACP Agents](/ar/tools/acp-agents#channel-specific-settings). +- إعداد قناة BlueBubbles الكامل موثّق في [BlueBubbles](/ar/channels/bluebubbles). ### iMessage -يقوم OpenClaw بتشغيل `imsg rpc` (JSON-RPC عبر stdio). لا حاجة إلى daemon أو منفذ. +يشغّل OpenClaw الأمر `imsg rpc` (JSON-RPC عبر stdio). لا حاجة إلى daemon أو منفذ. ```json5 { @@ -617,17 +617,17 @@ x-i18n: } ``` -- يتيح `channels.imessage.defaultAccount` الاختياري تجاوز اختيار الحساب الافتراضي عندما يطابق معرّف حساب مُعدّ. +- يجاوز `channels.imessage.defaultAccount` الاختياري اختيار الحساب الافتراضي عندما يطابق معرّف حساب مُعدّ. - يتطلب Full Disk Access إلى قاعدة بيانات Messages. -- يُفضّل استخدام أهداف `chat_id:`. استخدم `imsg chats --limit 20` لإدراج الدردشات. -- يمكن أن يشير `cliPath` إلى غلاف SSH؛ عيّن `remoteHost` (`host` أو `user@host`) لجلب المرفقات عبر SCP. +- يُفضَّل استخدام أهداف `chat_id:`. استخدم `imsg chats --limit 20` لسرد المحادثات. +- يمكن أن يشير `cliPath` إلى مغلف SSH؛ اضبط `remoteHost` (`host` أو `user@host`) لجلب المرفقات عبر SCP. - يقيّد `attachmentRoots` و`remoteAttachmentRoots` مسارات المرفقات الواردة (الافتراضي: `/Users/*/Library/Messages/Attachments`). -- يستخدم SCP التحقق الصارم من مفتاح المضيف، لذا تأكد من أن مفتاح مضيف المرحّل موجود مسبقًا في `~/.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). +- يستخدم SCP تحققاً صارماً من مفتاح المضيف، لذا تأكد من أن مفتاح مضيف الترحيل موجود مسبقاً في `~/.ssh/known_hosts`. +- يتحكم `channels.imessage.configWrites` في السماح أو منع عمليات كتابة الإعدادات التي تبدأ من iMessage. +- يمكن لإدخالات `bindings[]` ذات المستوى الأعلى مع `type: "acp"` ربط محادثات iMessage بجلسات ACP دائمة. استخدم مقبضاً مطبعاً أو هدف محادثة صريحاً (`chat_id:*` أو `chat_guid:*` أو `chat_identifier:*`) في `match.peer.id`. دلالات الحقول المشتركة: [ACP Agents](/ar/tools/acp-agents#channel-specific-settings). - + ```bash #!/usr/bin/env bash @@ -638,7 +638,7 @@ exec ssh -T gateway-host imsg "$@" ### Matrix -تأتي Matrix مدعومة عبر extension ويتم إعدادها تحت `channels.matrix`. +Matrix مدعوم عبر إضافة extension ويُعد ضمن `channels.matrix`. ```json5 { @@ -669,24 +669,24 @@ exec ssh -T gateway-host imsg "$@" ``` - تستخدم مصادقة الرمز المميز `accessToken`؛ وتستخدم مصادقة كلمة المرور `userId` + `password`. -- يوجّه `channels.matrix.proxy` حركة HTTP الخاصة بـ Matrix عبر وكيل HTTP(S) صريح. ويمكن للحسابات المسماة تجاوزه باستخدام `channels.matrix.accounts..proxy`. -- يسمح `channels.matrix.network.dangerouslyAllowPrivateNetwork` بخوادم homeserver الخاصة/الداخلية. و`proxy` وخيار الاشتراك في الشبكة هذا عنصران مستقلان. +- يوجّه `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`. +- تكون القيمة الافتراضية لـ `channels.matrix.autoJoin` هي `off`، لذا تُتجاهل الغرف المدعو إليها ودعوات الرسائل الخاصة الجديدة حتى تضبط `autoJoin: "allowlist"` مع `autoJoinAllowlist` أو `autoJoin: "always"`. +- `channels.matrix.execApprovals`: تسليم موافقات exec الأصلية في Matrix وتفويض الموافقين. + - `enabled`: `true` أو `false` أو `"auto"` (الافتراضي). في الوضع التلقائي، تُفعَّل موافقات exec عندما يمكن حل الموافقين من `approvers` أو `commands.ownerAllowFrom`. - `approvers`: معرّفات مستخدمي Matrix (مثل `@owner:example.org`) المسموح لهم بالموافقة على طلبات exec. - `agentFilter`: قائمة سماح اختيارية لمعرّفات الوكلاء. احذفها لتمرير الموافقات لجميع الوكلاء. - - `sessionFilter`: أنماط اختيارية لمفاتيح الجلسات (تطابق جزئي أو regex). + - `sessionFilter`: أنماط مفاتيح الجلسات الاختيارية (سلسلة فرعية أو regex). - `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.accounts..execApprovals`. +- يتحكم `channels.matrix.dm.sessionScope` في كيفية تجميع الرسائل الخاصة في Matrix داخل الجلسات: يشارك `per-user` (الافتراضي) حسب النظير الموجّه، بينما يعزل `per-room` كل غرفة رسائل خاصة. +- تستخدم مجسات حالة Matrix وعمليات البحث المباشر في الدليل نفس سياسة الوكيل المستخدمة لحركة وقت التشغيل. +- إعداد Matrix الكامل، وقواعد الاستهداف، وأمثلة الإعداد موثقة في [Matrix](/ar/channels/matrix). ### Microsoft Teams -تأتي Microsoft Teams مدعومة عبر extension ويتم إعدادها تحت `channels.msteams`. +Microsoft Teams مدعوم عبر extension ويُعد ضمن `channels.msteams`. ```json5 { @@ -702,11 +702,11 @@ exec ssh -T gateway-host imsg "$@" ``` - مسارات المفاتيح الأساسية المغطاة هنا: `channels.msteams` و`channels.msteams.configWrites`. -- تم توثيق إعدادات Teams الكاملة (بيانات الاعتماد، وwebhook، وسياسة الرسائل الخاصة/المجموعات، والتجاوزات لكل فريق/قناة) في [Microsoft Teams](/ar/channels/msteams). +- إعداد Teams الكامل (بيانات الاعتماد، webhook، سياسة الرسائل الخاصة/المجموعات، والتجاوزات لكل فريق/قناة) موثق في [Microsoft Teams](/ar/channels/msteams). ### IRC -تأتي IRC مدعومة عبر extension ويتم إعدادها تحت `channels.irc`. +IRC مدعوم عبر extension ويُعد ضمن `channels.irc`. ```json5 { @@ -728,12 +728,12 @@ exec ssh -T gateway-host imsg "$@" ``` - مسارات المفاتيح الأساسية المغطاة هنا: `channels.irc` و`channels.irc.dmPolicy` و`channels.irc.configWrites` و`channels.irc.nickserv.*`. -- يتيح `channels.irc.defaultAccount` الاختياري تجاوز اختيار الحساب الافتراضي عندما يطابق معرّف حساب مُعدّ. -- تم توثيق إعدادات قناة IRC الكاملة (المضيف/المنفذ/TLS/القنوات/قوائم السماح/فرض الإشارة) في [IRC](/ar/channels/irc). +- يجاوز `channels.irc.defaultAccount` الاختياري اختيار الحساب الافتراضي عندما يطابق معرّف حساب مُعدّ. +- إعداد قناة IRC الكامل (المضيف/المنفذ/TLS/القنوات/قوائم السماح/اشتراط الإشارة) موثق في [IRC](/ar/channels/irc). -### حسابات متعددة (جميع القنوات) +### الحسابات المتعددة (كل القنوات) -شغّل حسابات متعددة لكل قناة (لكل منها `accountId` خاص بها): +شغّل عدة حسابات لكل قناة (لكل منها `accountId` خاص بها): ```json5 { @@ -754,28 +754,28 @@ exec ssh -T gateway-host imsg "$@" } ``` -- يُستخدم `default` عند حذف `accountId` (في CLI + التوجيه). -- لا تنطبق رموز البيئة إلا على الحساب **الافتراضي**. +- يُستخدم `default` عندما يتم حذف `accountId` (في CLI + التوجيه). +- لا تنطبق رموز البيئة المميزة إلا على الحساب **default**. - تنطبق إعدادات القناة الأساسية على جميع الحسابات ما لم يتم تجاوزها لكل حساب. - استخدم `bindings[].match.accountId` لتوجيه كل حساب إلى وكيل مختلف. -- إذا أضفت حسابًا غير افتراضي عبر `openclaw channels add` (أو onboarding القناة) بينما لا تزال على إعداد قناة ذي حساب واحد على المستوى الأعلى، فسيقوم OpenClaw أولًا بترقية القيم ذات النطاق الحسابي على المستوى الأعلى الخاصة بالحساب الواحد إلى خريطة حسابات القناة حتى يستمر الحساب الأصلي في العمل. تنقل معظم القنوات هذه القيم إلى `channels..accounts.default`؛ ويمكن لـ Matrix بدلًا من ذلك الحفاظ على هدف مسمّى/افتراضي موجود ومطابق. -- تظل ارتباطات القناة فقط الموجودة حاليًا (من دون `accountId`) مطابقة للحساب الافتراضي؛ وتظل الارتباطات ذات النطاق الحسابي اختيارية. -- يقوم `openclaw doctor --fix` أيضًا بإصلاح الأشكال المختلطة عبر نقل القيم ذات النطاق الحسابي على المستوى الأعلى الخاصة بالحساب الواحد إلى الحساب المُرقّى المختار لتلك القناة. تستخدم معظم القنوات `accounts.default`؛ ويمكن لـ Matrix بدلًا من ذلك الحفاظ على هدف مسمّى/افتراضي موجود ومطابق. +- إذا أضفت حساباً غير افتراضي عبر `openclaw channels add` (أو عبر إعداد القناة) بينما ما زلت تستخدم إعداد قناة أحادي الحساب على المستوى الأعلى، فسيقوم OpenClaw أولاً بترقية القيم الأحادية الخاصة بالحساب الموجودة على المستوى الأعلى إلى خريطة حسابات القناة حتى يستمر الحساب الأصلي في العمل. تنقل معظم القنوات هذه القيم إلى `channels..accounts.default`؛ بينما يمكن لـ Matrix بدلاً من ذلك الإبقاء على هدف named/default مطابق موجود. +- تستمر الارتباطات الحالية الخاصة بالقناة فقط (من دون `accountId`) في مطابقة الحساب الافتراضي؛ وتبقى الارتباطات ذات النطاق الخاص بالحساب اختيارية. +- يقوم `openclaw doctor --fix` أيضاً بإصلاح الأشكال المختلطة عبر نقل القيم الأحادية على المستوى الأعلى ذات النطاق الخاص بالحساب إلى الحساب المُرقّى المختار لتلك القناة. تستخدم معظم القنوات `accounts.default`؛ بينما يمكن لـ Matrix الإبقاء على هدف named/default مطابق موجود. -### قنوات extension أخرى +### قنوات extension الأخرى -يتم إعداد العديد من قنوات extension على شكل `channels.` ويتم توثيقها في صفحات القنوات المخصصة لها (على سبيل المثال Feishu وMatrix وLINE وNostr وZalo وNextcloud Talk وSynology Chat وTwitch). +تُعدّ العديد من قنوات extension على شكل `channels.` ومُوثقة في صفحات القنوات المخصصة لها (على سبيل المثال Feishu وMatrix وLINE وNostr وZalo وNextcloud Talk وSynology Chat وTwitch). راجع فهرس القنوات الكامل: [القنوات](/ar/channels). -### فرض الإشارة في الدردشة الجماعية +### اشتراط الإشارة في الدردشة الجماعية -تفترض رسائل المجموعات افتراضيًا **اشتراط الإشارة** (إشارة في البيانات الوصفية أو أنماط regex آمنة). وينطبق ذلك على دردشات المجموعات في WhatsApp وTelegram وDiscord وGoogle Chat وiMessage. +تفترض رسائل المجموعات افتراضياً **اشتراط الإشارة** (إشارة من بيانات التعريف أو أنماط regex آمنة). ينطبق هذا على محادثات المجموعات في WhatsApp وTelegram وDiscord وGoogle Chat وiMessage. -**أنواع الإشارة:** +**أنواع الإشارات:** -- **الإشارات في البيانات الوصفية**: إشارات @-mentions الأصلية للمنصة. يتم تجاهلها في وضع الدردشة الذاتية في WhatsApp. -- **أنماط النص**: أنماط regex آمنة في `agents.list[].groupChat.mentionPatterns`. يتم تجاهل الأنماط غير الصالحة والتكرار المتداخل غير الآمن. -- لا يُفرض اشتراط الإشارة إلا عندما يكون الكشف ممكنًا (إشارات أصلية أو نمط واحد على الأقل). +- **إشارات بيانات التعريف**: إشارات @ الأصلية على المنصة. يتم تجاهلها في وضع الدردشة الذاتية في WhatsApp. +- **أنماط النص**: أنماط regex آمنة في `agents.list[].groupChat.mentionPatterns`. تُتجاهل الأنماط غير الصالحة والتكرار المتداخل غير الآمن. +- يُفرض اشتراط الإشارة فقط عندما يكون الاكتشاف ممكناً (إشارات أصلية أو نمط واحد على الأقل). ```json5 { @@ -788,7 +788,7 @@ exec ssh -T gateway-host imsg "$@" } ``` -يحدد `messages.groupChat.historyLimit` القيمة الافتراضية العامة. ويمكن للقنوات تجاوزها باستخدام `channels..historyLimit` (أو لكل حساب). اضبطها على `0` للتعطيل. +يضبط `messages.groupChat.historyLimit` القيمة الافتراضية العامة. ويمكن للقنوات تجاوزها عبر `channels..historyLimit` (أو لكل حساب). اضبط القيمة على `0` للتعطيل. #### حدود سجل الرسائل الخاصة @@ -805,13 +805,13 @@ exec ssh -T gateway-host imsg "$@" } ``` -آلية الحل: تجاوز لكل رسالة خاصة → افتراضي الموفر → بلا حد (الاحتفاظ بالكل). +آلية الحل: تجاوز لكل رسالة خاصة → القيمة الافتراضية للموفر → بلا حد (الاحتفاظ بكل شيء). مدعوم في: `telegram` و`whatsapp` و`discord` و`slack` و`signal` و`imessage` و`msteams`. #### وضع الدردشة الذاتية -أدرج رقمك الخاص في `allowFrom` لتفعيل وضع الدردشة الذاتية (يتجاهل إشارات @-mentions الأصلية، ويرد فقط على أنماط النص): +أدرج رقمك الخاص ضمن `allowFrom` لتفعيل وضع الدردشة الذاتية (يتجاهل إشارات @ الأصلية، ويستجيب فقط لأنماط النص): ```json5 { @@ -861,32 +861,32 @@ exec ssh -T gateway-host imsg "$@" -- تقوم هذه الكتلة بتهيئة أسطح الأوامر. للاطلاع على فهرس الأوامر الحالي المضمّن + المجمّع، راجع [Slash Commands](/ar/tools/slash-commands). -- هذه الصفحة هي **مرجع لمفاتيح الإعدادات**، وليست فهرس الأوامر الكامل. تُوثَّق الأوامر المملوكة للقنوات/الـ plugins مثل `/bot-ping` و`/bot-help` و`/bot-logs` الخاصة بـ QQ Bot، و`/card` الخاصة بـ LINE، و`/pair` الخاصة بـ device-pair، و`/dreaming` الخاصة بالذاكرة، و`/phone` الخاصة بـ phone-control، و`/voice` الخاصة بـ Talk في صفحات القنوات/الـ plugins الخاصة بها بالإضافة إلى [Slash Commands](/ar/tools/slash-commands). +- تهيئ هذه الكتلة أسطح الأوامر. للاطلاع على فهرس الأوامر الحالي المضمّن + المجمّع، راجع [Slash Commands](/ar/tools/slash-commands). +- هذه الصفحة هي **مرجع لمفاتيح الإعدادات**، وليست فهرس الأوامر الكامل. الأوامر المملوكة للقنوات/الـ plugin مثل `/bot-ping` و`/bot-help` و`/bot-logs` الخاصة بـ QQ Bot، و`/card` الخاصة بـ LINE، و`/pair` الخاصة بـ device-pair، و`/dreaming` الخاصة بالذاكرة، و`/phone` الخاصة بـ phone-control، و`/voice` الخاصة بـ Talk موثقة في صفحات القنوات/الـ plugin الخاصة بها بالإضافة إلى [Slash Commands](/ar/tools/slash-commands). - يجب أن تكون الأوامر النصية رسائل **مستقلة** مع `/` في البداية. -- يؤدي `native: "auto"` إلى تشغيل الأوامر الأصلية لـ Discord/Telegram، ويترك Slack معطلاً. -- يؤدي `nativeSkills: "auto"` إلى تشغيل أوامر Skills الأصلية لـ Discord/Telegram، ويترك Slack معطلاً. -- التجاوز لكل قناة: `channels.discord.commands.native` (قيمة منطقية أو `"auto"`). تؤدي القيمة `false` إلى مسح الأوامر المسجلة سابقًا. -- تجاوز تسجيل Skills الأصلية لكل قناة باستخدام `channels..commands.nativeSkills`. +- يؤدي `native: "auto"` إلى تشغيل الأوامر الأصلية في Discord/Telegram، ويترك Slack معطلاً. +- يؤدي `nativeSkills: "auto"` إلى تشغيل أوامر Skills الأصلية في Discord/Telegram، ويترك Slack معطلاً. +- يمكن التجاوز لكل قناة عبر `channels.discord.commands.native` (قيمة منطقية أو `"auto"`). تؤدي القيمة `false` إلى مسح الأوامر المسجلة مسبقاً. +- يمكن تجاوز تسجيل Skills الأصلية لكل قناة عبر `channels..commands.nativeSkills`. - يضيف `channels.telegram.customCommands` إدخالات إضافية إلى قائمة بوت Telegram. -- يؤدي `bash: true` إلى تفعيل `! ` لصدفة المضيف. ويتطلب `tools.elevated.enabled` وأن يكون المرسل ضمن `tools.elevated.allowFrom.`. -- يؤدي `config: true` إلى تفعيل `/config` (قراءة/كتابة `openclaw.json`). بالنسبة إلى عملاء `chat.send` في البوابة، تتطلب أيضًا عمليات الكتابة الدائمة عبر `/config set|unset` وجود `operator.admin`؛ بينما يبقى `/config show` للقراءة فقط متاحًا لعملاء المشغل العاديين ذوي نطاق الكتابة. -- يؤدي `mcp: true` إلى تفعيل `/mcp` لإعدادات خادم MCP التي يديرها OpenClaw تحت `mcp.servers`. -- يؤدي `plugins: true` إلى تفعيل `/plugins` لاكتشاف الـ plugins وتثبيتها وضوابط تمكينها/تعطيلها. -- يتحكم `channels..configWrites` في طفرات الإعدادات لكل قناة (الافتراضي: true). -- بالنسبة إلى القنوات متعددة الحسابات، يتحكم أيضًا `channels..accounts..configWrites` في عمليات الكتابة التي تستهدف ذلك الحساب (على سبيل المثال `/allowlist --config --account ` أو `/config set channels..accounts....`). -- يؤدي `restart: false` إلى تعطيل `/restart` وإجراءات أداة إعادة تشغيل البوابة. القيمة الافتراضية: `true`. -- تمثل `ownerAllowFrom` قائمة السماح الصريحة للمالك من أجل الأوامر/الأدوات الخاصة بالمالك فقط. وهي منفصلة عن `allowFrom`. -- يؤدي `ownerDisplay: "hash"` إلى تجزئة معرّفات المالك في مطالبة النظام. عيّن `ownerDisplaySecret` للتحكم في التجزئة. -- `allowFrom` مخصصة لكل موفر. عند تعيينها، تكون هي **المصدر الوحيد** للتفويض (ويتم تجاهل قوائم السماح/الاقتران الخاصة بالقناة و`useAccessGroups`). -- يؤدي `useAccessGroups: false` إلى السماح للأوامر بتجاوز سياسات مجموعات الوصول عندما لا تكون `allowFrom` معيّنة. -- خريطة وثائق الأوامر: +- يفعّل `bash: true` الأمر `! ` لصدفة المضيف. ويتطلب `tools.elevated.enabled` وأن يكون المرسل موجوداً في `tools.elevated.allowFrom.`. +- يفعّل `config: true` الأمر `/config` (لقراءة/كتابة `openclaw.json`). وبالنسبة إلى عملاء البوابة `chat.send`، تتطلب عمليات الكتابة الدائمة عبر `/config set|unset` أيضاً `operator.admin`؛ بينما يظل `/config show` للقراءة فقط متاحاً لعملاء المشغّل العاديين ذوي نطاق الكتابة. +- يفعّل `mcp: true` الأمر `/mcp` لإعداد خادم MCP الذي يديره OpenClaw ضمن `mcp.servers`. +- يفعّل `plugins: true` الأمر `/plugins` لاكتشاف الـ plugin وتثبيتها وعناصر التحكم في التفعيل/التعطيل. +- يتحكم `channels..configWrites` في تغييرات الإعدادات لكل قناة (الافتراضي: true). +- بالنسبة إلى القنوات متعددة الحسابات، يتحكم `channels..accounts..configWrites` أيضاً في عمليات الكتابة التي تستهدف ذلك الحساب (على سبيل المثال `/allowlist --config --account ` أو `/config set channels..accounts....`). +- يعطّل `restart: false` الأمر `/restart` وإجراءات أداة إعادة تشغيل البوابة. الافتراضي: `true`. +- تمثل `ownerAllowFrom` قائمة السماح الصريحة للمالك للأوامر/الأدوات الخاصة بالمالك فقط. وهي منفصلة عن `allowFrom`. +- تؤدي `ownerDisplay: "hash"` إلى تجزئة معرّفات المالك في مطالبة النظام. اضبط `ownerDisplaySecret` للتحكم في التجزئة. +- تكون `allowFrom` لكل موفّر. وعند تعيينها، تصبح **المصدر الوحيد** للتفويض (ويتم تجاهل قوائم السماح/الاقتران الخاصة بالقنوات و`useAccessGroups`). +- تسمح `useAccessGroups: false` للأوامر بتجاوز سياسات مجموعات الوصول عندما لا تكون `allowFrom` معينة. +- خريطة توثيق الأوامر: - الفهرس المضمّن + المجمّع: [Slash Commands](/ar/tools/slash-commands) - أسطح الأوامر الخاصة بالقنوات: [القنوات](/ar/channels) - أوامر QQ Bot: [QQ Bot](/ar/channels/qqbot) - - أوامر الاقتران: [الاقتران](/ar/channels/pairing) + - أوامر الاقتران: [Pairing](/ar/channels/pairing) - أمر البطاقة في LINE: [LINE](/ar/channels/line) - - dreaming الخاصة بالذاكرة: [Dreaming](/ar/concepts/dreaming) + - dreaming الخاص بالذاكرة: [Dreaming](/ar/concepts/dreaming) @@ -906,7 +906,7 @@ exec ssh -T gateway-host imsg "$@" ### `agents.defaults.repoRoot` -جذر مستودع اختياري يظهر في سطر Runtime ضمن مطالبة النظام. إذا لم يتم تعيينه، يكتشفه OpenClaw تلقائيًا عبر التتبع صعودًا من مساحة العمل. +جذر المستودع الاختياري المعروض في سطر Runtime ضمن مطالبة النظام. إذا لم يُعيَّن، يكتشفه OpenClaw تلقائياً عبر الصعود من مساحة العمل إلى الأعلى. ```json5 { @@ -916,7 +916,7 @@ exec ssh -T gateway-host imsg "$@" ### `agents.defaults.skills` -قائمة سماح افتراضية اختيارية لـ Skills للوكلاء الذين لا يعيّنون +قائمة السماح الافتراضية الاختيارية لـ Skills للوكلاء الذين لا يضبطون `agents.list[].skills`. ```json5 @@ -924,7 +924,7 @@ exec ssh -T gateway-host imsg "$@" agents: { defaults: { skills: ["github", "weather"] }, list: [ - { id: "writer" }, // يرث github, weather + { id: "writer" }, // يرث github وweather { id: "docs", skills: ["docs-search"] }, // يستبدل القيم الافتراضية { id: "locked-down", skills: [] }, // بلا Skills ], @@ -932,15 +932,15 @@ exec ssh -T gateway-host imsg "$@" } ``` -- احذف `agents.defaults.skills` للحصول على Skills غير مقيّدة افتراضيًا. +- احذف `agents.defaults.skills` للسماح بكل Skills افتراضياً من دون قيود. - احذف `agents.list[].skills` لوراثة القيم الافتراضية. -- عيّن `agents.list[].skills: []` لعدم استخدام أي Skills. -- تمثل القائمة غير الفارغة في `agents.list[].skills` المجموعة النهائية لذلك الوكيل؛ - ولا تُدمج مع القيم الافتراضية. +- اضبط `agents.list[].skills: []` لعدم استخدام أي Skills. +- تمثل قائمة `agents.list[].skills` غير الفارغة المجموعة النهائية لذلك الوكيل؛ + ولا تندمج مع القيم الافتراضية. ### `agents.defaults.skipBootstrap` -يعطّل الإنشاء التلقائي لملفات bootstrap الخاصة بمساحة العمل (`AGENTS.md` و`SOUL.md` و`TOOLS.md` و`IDENTITY.md` و`USER.md` و`HEARTBEAT.md` و`BOOTSTRAP.md`). +يعطّل الإنشاء التلقائي لملفات التمهيد الخاصة بمساحة العمل (`AGENTS.md` و`SOUL.md` و`TOOLS.md` و`IDENTITY.md` و`USER.md` و`HEARTBEAT.md` و`BOOTSTRAP.md`). ```json5 { @@ -950,9 +950,9 @@ exec ssh -T gateway-host imsg "$@" ### `agents.defaults.contextInjection` -يتحكم في توقيت حقن ملفات bootstrap الخاصة بمساحة العمل في مطالبة النظام. الافتراضي: `"always"`. +يتحكم في وقت حقن ملفات التمهيد الخاصة بمساحة العمل داخل مطالبة النظام. الافتراضي: `"always"`. -- `"continuation-skip"`: تتجاوز أدوار المتابعة الآمنة (بعد اكتمال رد المساعد) إعادة حقن bootstrap الخاصة بمساحة العمل، مما يقلل حجم المطالبة. وتظل تشغيلات النبض وإعادات المحاولة بعد الضغط تعيد بناء السياق. +- `"continuation-skip"`: تتخطى أدوار الاستكمال الآمنة (بعد اكتمال رد المساعد) إعادة حقن تمهيد مساحة العمل، مما يقلل حجم المطالبة. وتظل عمليات heartbeat وإعادات المحاولة بعد الضغط تعيد بناء السياق. ```json5 { @@ -962,7 +962,7 @@ exec ssh -T gateway-host imsg "$@" ### `agents.defaults.bootstrapMaxChars` -الحد الأقصى لعدد الأحرف لكل ملف bootstrap في مساحة العمل قبل الاقتطاع. الافتراضي: `20000`. +الحد الأقصى لعدد الأحرف لكل ملف تمهيد لمساحة العمل قبل الاقتطاع. الافتراضي: `20000`. ```json5 { @@ -972,7 +972,7 @@ exec ssh -T gateway-host imsg "$@" ### `agents.defaults.bootstrapTotalMaxChars` -الحد الأقصى لإجمالي الأحرف المحقونة عبر جميع ملفات bootstrap في مساحة العمل. الافتراضي: `150000`. +الحد الأقصى الإجمالي لعدد الأحرف المحقونة عبر جميع ملفات تمهيد مساحة العمل. الافتراضي: `150000`. ```json5 { @@ -982,12 +982,12 @@ exec ssh -T gateway-host imsg "$@" ### `agents.defaults.bootstrapPromptTruncationWarning` -يتحكم في نص التحذير المرئي للوكيل عند اقتطاع سياق bootstrap. +يتحكم في نص التحذير المرئي للوكيل عندما يتم اقتطاع سياق التمهيد. الافتراضي: `"once"`. -- `"off"`: لا تحقن نص التحذير أبدًا في مطالبة النظام. -- `"once"`: احقن التحذير مرة واحدة لكل توقيع اقتطاع فريد (موصى به). -- `"always"`: احقن التحذير في كل تشغيل عند وجود اقتطاع. +- `"off"`: لا يحقن نص التحذير أبداً في مطالبة النظام. +- `"once"`: يحقن التحذير مرة واحدة لكل توقيع اقتطاع فريد (موصى به). +- `"always"`: يحقن التحذير في كل تشغيل عند وجود اقتطاع. ```json5 { @@ -997,10 +997,10 @@ exec ssh -T gateway-host imsg "$@" ### `agents.defaults.imageMaxDimensionPx` -أقصى حجم بالبكسل لأطول ضلع في الصورة داخل كتل صور السجل/الأدوات قبل استدعاءات الموفر. +الحد الأقصى لحجم البكسلات لأطول ضلع في الصورة داخل كتل صور السجل/الأدوات قبل استدعاءات الموفّر. الافتراضي: `1200`. -تقلل القيم الأدنى عادةً من استخدام رموز الرؤية وحجم حمولة الطلب عند التشغيلات التي تحتوي على الكثير من لقطات الشاشة. +تقلل القيم الأدنى عادةً من استخدام رموز الرؤية وحجم حمولة الطلب في التشغيلات التي تحتوي على لقطات شاشة كثيرة. وتحافظ القيم الأعلى على مزيد من التفاصيل البصرية. ```json5 @@ -1011,7 +1011,7 @@ exec ssh -T gateway-host imsg "$@" ### `agents.defaults.userTimezone` -المنطقة الزمنية لسياق مطالبة النظام (وليس للطوابع الزمنية للرسائل). وتعود احتياطيًا إلى المنطقة الزمنية للمضيف. +المنطقة الزمنية لسياق مطالبة النظام (وليس للطوابع الزمنية للرسائل). تعود إلى المنطقة الزمنية للمضيف. ```json5 { @@ -1059,7 +1059,7 @@ exec ssh -T gateway-host imsg "$@" primary: "anthropic/claude-opus-4-6", fallbacks: ["openai/gpt-5.4-mini"], }, - params: { cacheRetention: "long" }, // القيم الافتراضية العامة لمعاملات الموفر + params: { cacheRetention: "long" }, // القيم الافتراضية العامة لمعاملات الموفّر embeddedHarness: { runtime: "auto", // auto | pi | registered harness id, e.g. codex fallback: "pi", // pi | none @@ -1078,48 +1078,48 @@ exec ssh -T gateway-host imsg "$@" } ``` -- `model`: يقبل إما سلسلة (`"provider/model"`) أو كائنًا (`{ primary, fallbacks }`). - - يعيّن شكل السلسلة النموذج الأساسي فقط. - - يعيّن شكل الكائن النموذج الأساسي بالإضافة إلى نماذج التحويل الاحتياطي المرتبة. -- `imageModel`: يقبل إما سلسلة (`"provider/model"`) أو كائنًا (`{ primary, fallbacks }`). - - يُستخدم بواسطة مسار أداة `image` بوصفه إعداد نموذج الرؤية الخاص بها. - - ويُستخدم أيضًا للتوجيه الاحتياطي عندما لا يستطيع النموذج المحدد/الافتراضي قبول إدخال الصور. -- `imageGenerationModel`: يقبل إما سلسلة (`"provider/model"`) أو كائنًا (`{ primary, fallbacks }`). - - يُستخدم بواسطة إمكانية توليد الصور المشتركة وأي سطح أداة/plugin مستقبلي يولّد الصور. - - القيم النموذجية: `google/gemini-3.1-flash-image-preview` لتوليد صور Gemini الأصلي، أو `fal/fal-ai/flux/dev` لـ fal، أو `openai/gpt-image-1` لـ OpenAI Images. - - إذا حددت موفرًا/نموذجًا مباشرةً، فقم أيضًا بإعداد مصادقة/مفتاح API للموفر المطابق (على سبيل المثال `GEMINI_API_KEY` أو `GOOGLE_API_KEY` لـ `google/*`، و`OPENAI_API_KEY` لـ `openai/*`، و`FAL_KEY` لـ `fal/*`). - - إذا تم حذفه، فلا يزال بإمكان `image_generate` استنتاج موفر افتراضي مدعوم بالمصادقة. إذ يحاول أولًا الموفر الافتراضي الحالي، ثم بقية موفري توليد الصور المسجلين بترتيب معرّفات الموفرين. -- `musicGenerationModel`: يقبل إما سلسلة (`"provider/model"`) أو كائنًا (`{ primary, fallbacks }`). - - يُستخدم بواسطة إمكانية توليد الموسيقى المشتركة وأداة `music_generate` المضمّنة. +- تقبل `model` إما سلسلة (`"provider/model"`) أو كائناً (`{ primary, fallbacks }`). + - يضبط الشكل النصي النموذج الأساسي فقط. + - يضبط شكل الكائن النموذج الأساسي بالإضافة إلى نماذج التبديل الاحتياطي المرتبة. +- تقبل `imageModel` إما سلسلة (`"provider/model"`) أو كائناً (`{ primary, fallbacks }`). + - تُستخدم في مسار أداة `image` بوصفها إعداد نموذج الرؤية. + - وتُستخدم أيضاً كتوجيه احتياطي عندما لا يتمكن النموذج المحدد/الافتراضي من قبول إدخال الصور. +- تقبل `imageGenerationModel` إما سلسلة (`"provider/model"`) أو كائناً (`{ primary, fallbacks }`). + - تُستخدم في إمكانية توليد الصور المشتركة وأي سطح أداة/Plugin مستقبلي يولّد الصور. + - القيم النموذجية: `google/gemini-3.1-flash-image-preview` لتوليد الصور الأصلي في Gemini، أو `fal/fal-ai/flux/dev` لـ fal، أو `openai/gpt-image-1` لـ OpenAI Images. + - إذا اخترت موفّراً/نموذجاً مباشرةً، فاضبط أيضاً مصادقة الموفّر/مفتاح API المطابق (على سبيل المثال `GEMINI_API_KEY` أو `GOOGLE_API_KEY` لـ `google/*`، و`OPENAI_API_KEY` لـ `openai/*`، و`FAL_KEY` لـ `fal/*`). + - إذا حُذف، فلا تزال `image_generate` قادرة على استنتاج قيمة افتراضية لموفّر مدعوم بالمصادقة. فهي تحاول أولاً الموفّر الافتراضي الحالي، ثم بقية موفّري توليد الصور المسجلين بترتيب معرّف الموفّر. +- تقبل `musicGenerationModel` إما سلسلة (`"provider/model"`) أو كائناً (`{ primary, fallbacks }`). + - تُستخدم في إمكانية توليد الموسيقى المشتركة وفي أداة `music_generate` المضمنة. - القيم النموذجية: `google/lyria-3-clip-preview` أو `google/lyria-3-pro-preview` أو `minimax/music-2.5+`. - - إذا تم حذفه، فلا يزال بإمكان `music_generate` استنتاج موفر افتراضي مدعوم بالمصادقة. إذ يحاول أولًا الموفر الافتراضي الحالي، ثم بقية موفري توليد الموسيقى المسجلين بترتيب معرّفات الموفرين. - - إذا حددت موفرًا/نموذجًا مباشرةً، فقم أيضًا بإعداد مصادقة/مفتاح API للموفر المطابق. -- `videoGenerationModel`: يقبل إما سلسلة (`"provider/model"`) أو كائنًا (`{ primary, fallbacks }`). - - يُستخدم بواسطة إمكانية توليد الفيديو المشتركة وأداة `video_generate` المضمّنة. + - إذا حُذف، فلا تزال `music_generate` قادرة على استنتاج قيمة افتراضية لموفّر مدعوم بالمصادقة. فهي تحاول أولاً الموفّر الافتراضي الحالي، ثم بقية موفّري توليد الموسيقى المسجلين بترتيب معرّف الموفّر. + - إذا اخترت موفّراً/نموذجاً مباشرةً، فاضبط أيضاً مصادقة الموفّر/مفتاح API المطابق. +- تقبل `videoGenerationModel` إما سلسلة (`"provider/model"`) أو كائناً (`{ primary, fallbacks }`). + - تُستخدم في إمكانية توليد الفيديو المشتركة وفي أداة `video_generate` المضمنة. - القيم النموذجية: `qwen/wan2.6-t2v` أو `qwen/wan2.6-i2v` أو `qwen/wan2.6-r2v` أو `qwen/wan2.6-r2v-flash` أو `qwen/wan2.7-r2v`. - - إذا تم حذفه، فلا يزال بإمكان `video_generate` استنتاج موفر افتراضي مدعوم بالمصادقة. إذ يحاول أولًا الموفر الافتراضي الحالي، ثم بقية موفري توليد الفيديو المسجلين بترتيب معرّفات الموفرين. - - إذا حددت موفرًا/نموذجًا مباشرةً، فقم أيضًا بإعداد مصادقة/مفتاح API للموفر المطابق. - - يدعم موفر توليد الفيديو Qwen المضمّن ما يصل إلى فيديو خرج واحد، وصورة إدخال واحدة، و4 مقاطع فيديو إدخال، ومدة 10 ثوانٍ، وخيارات `size` و`aspectRatio` و`resolution` و`audio` و`watermark` على مستوى الموفر. -- `pdfModel`: يقبل إما سلسلة (`"provider/model"`) أو كائنًا (`{ primary, fallbacks }`). - - يُستخدم بواسطة أداة `pdf` لتوجيه النموذج. - - إذا تم حذفه، تعود أداة PDF احتياطيًا إلى `imageModel`، ثم إلى النموذج المحلول للجلسة/الافتراضي. + - إذا حُذف، فلا تزال `video_generate` قادرة على استنتاج قيمة افتراضية لموفّر مدعوم بالمصادقة. فهي تحاول أولاً الموفّر الافتراضي الحالي، ثم بقية موفّري توليد الفيديو المسجلين بترتيب معرّف الموفّر. + - إذا اخترت موفّراً/نموذجاً مباشرةً، فاضبط أيضاً مصادقة الموفّر/مفتاح API المطابق. + - يدعم موفّر توليد الفيديو Qwen المضمّن حتى فيديو إخراج واحداً، وصورة إدخال واحدة، و4 فيديوهات إدخال، ومدة 10 ثوانٍ، وخيارات `size` و`aspectRatio` و`resolution` و`audio` و`watermark` على مستوى الموفّر. +- تقبل `pdfModel` إما سلسلة (`"provider/model"`) أو كائناً (`{ primary, fallbacks }`). + - تُستخدم بواسطة أداة `pdf` لتوجيه النموذج. + - إذا حُذف، تعود أداة PDF إلى `imageModel`، ثم إلى النموذج المحلول للجلسة/الافتراضي. - `pdfMaxBytesMb`: حد حجم PDF الافتراضي لأداة `pdf` عندما لا يتم تمرير `maxBytesMb` وقت الاستدعاء. -- `pdfMaxPages`: الحد الأقصى الافتراضي للصفحات التي يأخذها وضع الاستخراج الاحتياطي في أداة `pdf` في الاعتبار. +- `pdfMaxPages`: الحد الأقصى الافتراضي للصفحات التي تؤخذ في الاعتبار بواسطة وضع الاستخراج الاحتياطي في أداة `pdf`. - `verboseDefault`: مستوى verbose الافتراضي للوكلاء. القيم: `"off"` و`"on"` و`"full"`. الافتراضي: `"off"`. -- `elevatedDefault`: مستوى المخرجات المرتفعة الافتراضي للوكلاء. القيم: `"off"` و`"on"` و`"ask"` و`"full"`. الافتراضي: `"on"`. -- `model.primary`: بالصيغة `provider/model` (مثل `openai/gpt-5.4`). إذا حذفت الموفر، يحاول OpenClaw أولًا اسمًا مستعارًا، ثم مطابقة فريدة لموفر مُعد لذلك مع معرّف النموذج المطابق تمامًا، وبعد ذلك فقط يعود احتياطيًا إلى الموفر الافتراضي المُعد (سلوك توافق قديم، لذا يُفضَّل استخدام `provider/model` بشكل صريح). إذا لم يعد ذلك الموفر يعرّض النموذج الافتراضي المُعد، فسيعود OpenClaw احتياطيًا إلى أول موفر/نموذج مُعد بدلًا من إظهار افتراضي قديم لموفر تمت إزالته. -- `models`: فهرس النماذج المُعد وقائمة السماح لـ `/model`. يمكن أن يتضمن كل إدخال `alias` (اختصارًا) و`params` (خاصة بالموفر، مثل `temperature` و`maxTokens` و`cacheRetention` و`context1m`). -- `params`: معاملات الموفر الافتراضية العامة المطبقة على جميع النماذج. يتم تعيينها في `agents.defaults.params` (مثل `{ cacheRetention: "long" }`). -- أسبقية دمج `params` (في الإعدادات): يتم تجاوز `agents.defaults.params` (الأساس العام) بواسطة `agents.defaults.models["provider/model"].params` (لكل نموذج)، ثم تتجاوزه `agents.list[].params` (لمعرّف الوكيل المطابق) بحسب المفتاح. راجع [Prompt Caching](/ar/reference/prompt-caching) للتفاصيل. -- `embeddedHarness`: سياسة وقت التشغيل الافتراضية منخفضة المستوى للوكلاء المضمّنين. استخدم `runtime: "auto"` للسماح لـ plugin harnesses المسجلة باحتواء النماذج المدعومة، أو `runtime: "pi"` لفرض PI harness المضمّن، أو معرّف harness مسجل مثل `runtime: "codex"`. عيّن `fallback: "none"` لتعطيل العودة التلقائية إلى PI. -- تحفظ كاتبات الإعدادات التي تعدّل هذه الحقول (على سبيل المثال `/models set` و`/models set-image` وأوامر إضافة/إزالة الاحتياطي) الشكل القياسي للكائن، وتحافظ على قوائم الاحتياطي الموجودة عند الإمكان. -- `maxConcurrent`: الحد الأقصى لتشغيلات الوكلاء المتوازية عبر الجلسات (مع بقاء كل جلسة متسلسلة). الافتراضي: 4. +- `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` (لمعرّف الوكيل المطابق) حسب المفتاح. راجع [Prompt Caching](/ar/reference/prompt-caching) للتفاصيل. +- `embeddedHarness`: سياسة وقت التشغيل المضمن منخفض المستوى الافتراضية للوكلاء. استخدم `runtime: "auto"` للسماح لـ plugin harnesses المسجلة بالمطالبة بالنماذج المدعومة، أو `runtime: "pi"` لفرض PI harness المضمّن، أو معرّف harness مسجل مثل `runtime: "codex"`. اضبط `fallback: "none"` لتعطيل الرجوع التلقائي إلى PI. +- تحفظ أدوات كتابة الإعدادات التي تعدّل هذه الحقول (على سبيل المثال `/models set` و`/models set-image` وأوامر إضافة/إزالة الاحتياطي) شكل الكائن القياسي وتحافظ على قوائم الاحتياطي الموجودة متى أمكن. +- `maxConcurrent`: الحد الأقصى للتشغيلات المتوازية للوكلاء عبر الجلسات (مع بقاء كل جلسة متسلسلة داخلياً). الافتراضي: 4. ### `agents.defaults.embeddedHarness` -يتحكم `embeddedHarness` في المنفذ منخفض المستوى الذي يشغّل أدوار الوكيل المضمّن. -ينبغي لمعظم عمليات النشر الإبقاء على القيمة الافتراضية `{ runtime: "auto", fallback: "pi" }`. -استخدمه عندما يوفّر plugin موثوق harness أصليًا، مثل +يتحكم `embeddedHarness` في أي منفّذ منخفض المستوى يشغّل أدوار الوكيل المضمنة. +يجب على معظم البيئات الاحتفاظ بالقيمة الافتراضية `{ runtime: "auto", fallback: "pi" }`. +استخدمه عندما يوفّر plugin موثوق harness أصلياً، مثل Codex app-server harness المضمّن. ```json5 @@ -1136,34 +1136,34 @@ Codex app-server harness المضمّن. } ``` -- `runtime`: `"auto"` أو `"pi"` أو معرّف plugin harness مسجل. يسجل plugin Codex المضمّن `codex`. -- `fallback`: `"pi"` أو `"none"`. تُبقي `"pi"` على PI harness المضمّن بوصفه احتياطي التوافق. وتجعل `"none"` اختيار plugin harness المفقود أو غير المدعوم يفشل بدلًا من استخدام PI بصمت. -- تجاوزات البيئة: يتجاوز `OPENCLAW_AGENT_RUNTIME=` قيمة `runtime`؛ ويعطّل `OPENCLAW_AGENT_HARNESS_FALLBACK=none` العودة إلى PI لتلك العملية. -- لعمليات النشر الخاصة بـ Codex فقط، عيّن `model: "codex/gpt-5.4"` و`embeddedHarness.runtime: "codex"` و`embeddedHarness.fallback: "none"`. -- يتحكم هذا فقط في chat harness المضمّن. أما توليد الوسائط، والرؤية، وPDF، والموسيقى، والفيديو، وTTS فما تزال تستخدم إعدادات الموفر/النموذج الخاصة بها. +- `runtime`: `"auto"` أو `"pi"` أو معرّف harness plugin مسجل. يسجّل Codex plugin المضمّن القيمة `codex`. +- `fallback`: `"pi"` أو `"none"`. تُبقي `"pi"` على PI harness المضمّن كخيار احتياطي للتوافق. وتجعل `"none"` غياب اختيار plugin harness أو عدم دعمه يؤدي إلى الفشل بدلاً من استخدام PI بصمت. +- تجاوزات البيئة: تؤدي `OPENCLAW_AGENT_RUNTIME=` إلى تجاوز `runtime`؛ وتؤدي `OPENCLAW_AGENT_HARNESS_FALLBACK=none` إلى تعطيل الرجوع إلى PI لهذه العملية. +- في البيئات المخصصة لـ Codex فقط، اضبط `model: "codex/gpt-5.4"` و`embeddedHarness.runtime: "codex"` و`embeddedHarness.fallback: "none"`. +- يتحكم هذا فقط في chat harness المضمن. أما توليد الوسائط والرؤية وPDF والموسيقى والفيديو وTTS فتبقى تستخدم إعدادات الموفّر/النموذج الخاصة بها. -**اختصارات الأسماء المستعارة المضمّنة** (لا تنطبق إلا عندما يكون النموذج موجودًا في `agents.defaults.models`): +**اختصارات alias المضمنة** (لا تنطبق إلا عندما يكون النموذج موجوداً في `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` | +| Alias | النموذج | +| ------------------- | -------------------------------------- | +| `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 { @@ -1191,13 +1191,13 @@ Codex app-server harness المضمّن. } ``` -- واجهات CLI الخلفية نصية أولًا؛ وتكون الأدوات دائمًا معطلة. -- الجلسات مدعومة عندما يتم تعيين `sessionArg`. -- تمرير الصور مدعوم عندما يقبل `imageArg` مسارات الملفات. +- واجهات CLI الخلفية موجهة للنص أولاً؛ وتكون الأدوات معطلة دائماً. +- تكون الجلسات مدعومة عندما يكون `sessionArg` مضبوطاً. +- يكون تمرير الصور مدعوماً عندما يقبل `imageArg` مسارات الملفات. ### `agents.defaults.systemPromptOverride` -استبدل مطالبة النظام الكاملة التي يجمعها OpenClaw بسلسلة ثابتة. عيّنها على المستوى الافتراضي (`agents.defaults.systemPromptOverride`) أو لكل وكيل (`agents.list[].systemPromptOverride`). وتكون القيم لكل وكيل لها الأولوية؛ ويتم تجاهل القيم الفارغة أو التي تحتوي على مسافات فقط. وهي مفيدة لتجارب المطالبات المضبوطة. +استبدل مطالبة النظام الكاملة التي يجمعها OpenClaw بسلسلة ثابتة. اضبطها على المستوى الافتراضي (`agents.defaults.systemPromptOverride`) أو لكل وكيل (`agents.list[].systemPromptOverride`). تكون القيم الخاصة بكل وكيل ذات أولوية أعلى؛ ويتم تجاهل القيمة الفارغة أو التي تحتوي على مسافات بيضاء فقط. وهي مفيدة لتجارب prompt المضبوطة. ```json5 { @@ -1211,7 +1211,7 @@ Codex app-server harness المضمّن. ### `agents.defaults.heartbeat` -تشغيلات النبض الدورية. +تشغيلات heartbeat الدورية. ```json5 { @@ -1238,15 +1238,15 @@ Codex app-server harness المضمّن. } ``` -- `every`: سلسلة مدة (ms/s/m/h). الافتراضي: `30m` (مصادقة مفتاح API) أو `1h` (مصادقة OAuth). عيّنه إلى `0m` للتعطيل. -- `includeSystemPromptSection`: عند تعيينه إلى false، يحذف قسم Heartbeat من مطالبة النظام ويتجاوز حقن `HEARTBEAT.md` في سياق bootstrap. الافتراضي: `true`. -- `suppressToolErrorWarnings`: عند تعيينه إلى true، يمنع حمولات تحذير أخطاء الأدوات أثناء تشغيلات النبض. -- `timeoutSeconds`: الحد الأقصى للوقت بالثواني المسموح به لدور وكيل نبض قبل إيقافه. اتركه غير معيّن لاستخدام `agents.defaults.timeoutSeconds`. -- `directPolicy`: سياسة التسليم المباشر/الرسائل الخاصة. تسمح `allow` (الافتراضي) بالتسليم إلى هدف مباشر. وتمنع `block` التسليم إلى الهدف المباشر وتصدر `reason=dm-blocked`. -- `lightContext`: عند تعيينه إلى true، تستخدم تشغيلات النبض سياق bootstrap خفيفًا وتحتفظ فقط بـ `HEARTBEAT.md` من ملفات bootstrap الخاصة بمساحة العمل. -- `isolatedSession`: عند تعيينه إلى true، يعمل كل نبض في جلسة جديدة من دون أي سجل محادثات سابق. وهو نفس نمط العزل في cron `sessionTarget: "isolated"`. ويقلل تكلفة الرموز لكل نبض من نحو 100 ألف إلى نحو 2-5 آلاف رمز. -- لكل وكيل: عيّن `agents.list[].heartbeat`. عندما يحدد أي وكيل `heartbeat`، **فإن هؤلاء الوكلاء فقط** هم الذين يشغّلون النبض. -- تشغّل عمليات النبض أدوار وكيل كاملة — والفواصل الأقصر تستهلك مزيدًا من الرموز. +- `every`: سلسلة مدة (ms/s/m/h). الافتراضي: `30m` (مصادقة مفتاح API) أو `1h` (مصادقة OAuth). اضبطها على `0m` للتعطيل. +- `includeSystemPromptSection`: عند القيمة false، يحذف قسم Heartbeat من مطالبة النظام ويتخطى حقن `HEARTBEAT.md` في سياق التمهيد. الافتراضي: `true`. +- `suppressToolErrorWarnings`: عند القيمة true، يحجب حمولات تحذير أخطاء الأدوات أثناء تشغيلات heartbeat. +- `timeoutSeconds`: الحد الأقصى للوقت بالثواني المسموح به لدور وكيل heartbeat قبل إيقافه. اتركه غير مضبوط لاستخدام `agents.defaults.timeoutSeconds`. +- `directPolicy`: سياسة التسليم المباشر/الرسائل الخاصة. تسمح `allow` (الافتراضي) بالتسليم المباشر إلى الهدف. وتمنع `block` التسليم المباشر إلى الهدف وتنتج `reason=dm-blocked`. +- `lightContext`: عند القيمة true، تستخدم تشغيلات heartbeat سياق تمهيد خفيفاً وتحتفظ فقط بملف `HEARTBEAT.md` من ملفات تمهيد مساحة العمل. +- `isolatedSession`: عند القيمة true، يعمل كل heartbeat في جلسة جديدة بلا سجل محادثة سابق. وهو نفس نمط العزل في cron `sessionTarget: "isolated"`. ويقلل كلفة الرموز لكل heartbeat من نحو ~100K إلى ~2-5K رموز. +- لكل وكيل: اضبط `agents.list[].heartbeat`. عندما يعرّف أي وكيل `heartbeat`، **لا يشغّل heartbeat إلا هؤلاء الوكلاء فقط**. +- تنفّذ heartbeat أدوار وكيل كاملة — الفواصل الأقصر تستهلك مزيداً من الرموز. ### `agents.defaults.compaction` @@ -1276,19 +1276,19 @@ Codex app-server harness المضمّن. } ``` -- `mode`: ‏`default` أو `safeguard` (تلخيص مجزأ للسجلات الطويلة). راجع [Compaction](/ar/concepts/compaction). -- `provider`: معرّف plugin موفر compaction مسجل. عند تعيينه، يتم استدعاء `summarize()` الخاصة بالموفر بدلًا من تلخيص LLM المضمّن. ويعود احتياطيًا إلى التلخيص المضمّن عند الفشل. ويؤدي تعيين موفر إلى فرض `mode: "safeguard"`. راجع [Compaction](/ar/concepts/compaction). -- `timeoutSeconds`: الحد الأقصى بالثواني المسموح به لعملية compaction واحدة قبل أن يوقفها OpenClaw. الافتراضي: `900`. -- `identifierPolicy`: ‏`strict` (الافتراضي) أو `off` أو `custom`. تضيف `strict` تلقائيًا إرشادات مضمّنة للحفاظ على المعرّفات غير الشفافة أثناء تلخيص compaction. -- `identifierInstructions`: نص مخصص اختياري للحفاظ على المعرّفات يُستخدم عندما يكون `identifierPolicy=custom`. -- `postCompactionSections`: أسماء أقسام H2/H3 اختيارية من `AGENTS.md` لإعادة حقنها بعد compaction. القيمة الافتراضية هي `["Session Startup", "Red Lines"]`؛ عيّن `[]` لتعطيل إعادة الحقن. عند عدم تعيينها أو عند تعيين هذا الزوج الافتراضي صراحة، تُقبل أيضًا العناوين الأقدم `Every Session`/`Safety` كخيار احتياطي قديم. -- `model`: تجاوز اختياري من نوع `provider/model-id` لتلخيص compaction فقط. استخدم هذا عندما ينبغي أن تحتفظ الجلسة الرئيسية بنموذج معيّن بينما تعمل ملخصات compaction على نموذج آخر؛ وعند عدم تعيينه، تستخدم compaction النموذج الأساسي للجلسة. -- `notifyUser`: عند تعيينه إلى `true`، يرسل إشعارًا موجزًا إلى المستخدم عند بدء compaction (مثل "Compacting context..."). يكون معطلًا افتراضيًا لإبقاء compaction صامتًا. +- `mode`: ‏`default` أو `safeguard` (تلخيص مجزأ للتواريخ الطويلة). راجع [Compaction](/ar/concepts/compaction). +- `provider`: معرّف plugin موفّر compaction مسجل. عند تعيينه، يتم استدعاء `summarize()` الخاصة بالموفّر بدلاً من تلخيص LLM المضمن. ويعود إلى المضمن عند الفشل. ويؤدي تعيين موفّر إلى فرض `mode: "safeguard"`. راجع [Compaction](/ar/concepts/compaction). +- `timeoutSeconds`: الحد الأقصى بالثواني المسموح به لعملية compaction واحدة قبل أن يقوم OpenClaw بإيقافها. الافتراضي: `900`. +- `identifierPolicy`: ‏`strict` (الافتراضي) أو `off` أو `custom`. تضيف `strict` إرشادات مضمّنة للاحتفاظ بالمعرّفات غير الشفافة قبل تلخيص compaction. +- `identifierInstructions`: نص مخصص اختياري للحفاظ على المعرّفات يُستخدم عندما تكون `identifierPolicy=custom`. +- `postCompactionSections`: أسماء أقسام H2/H3 اختيارية من `AGENTS.md` لإعادة حقنها بعد compaction. القيمة الافتراضية هي `["Session Startup", "Red Lines"]`؛ اضبطها على `[]` لتعطيل إعادة الحقن. وعند تركها غير معيّنة أو تعيينها صراحةً إلى هذا الزوج الافتراضي، تُقبل أيضاً عناوين `Every Session`/`Safety` الأقدم كخيار احتياطي قديم. +- `model`: تجاوز اختياري بصيغة `provider/model-id` لتلخيص compaction فقط. استخدمه عندما يجب أن تحتفظ الجلسة الرئيسية بنموذج معيّن بينما تعمل ملخصات compaction على نموذج آخر؛ وعند عدم تعيينه، تستخدم compaction النموذج الأساسي للجلسة. +- `notifyUser`: عندما تكون `true`، يرسل إشعاراً موجزاً إلى المستخدم عند بدء compaction (على سبيل المثال: "Compacting context..."). يكون معطلاً افتراضياً حتى تظل compaction صامتة. - `memoryFlush`: دور وكيل صامت قبل compaction التلقائي لتخزين الذكريات الدائمة. ويتم تخطيه عندما تكون مساحة العمل للقراءة فقط. ### `agents.defaults.contextPruning` -يقوم بتقليم **نتائج الأدوات القديمة** من السياق الموجود في الذاكرة قبل الإرسال إلى LLM. ولا يُعدّل سجل الجلسة على القرص. +يقتطع **نتائج الأدوات القديمة** من السياق الموجود في الذاكرة قبل الإرسال إلى LLM. ولا **يعدّل** سجل الجلسة على القرص. ```json5 { @@ -1312,25 +1312,25 @@ Codex app-server harness المضمّن. -- يؤدي `mode: "cache-ttl"` إلى تفعيل تمريرات التقليم. -- يتحكم `ttl` في عدد المرات التي يمكن بعدها تشغيل التقليم مجددًا (بعد آخر لمسة لذاكرة التخزين المؤقت). -- يقوم التقليم أولًا بالاقتطاع المرن لنتائج الأدوات كبيرة الحجم، ثم يزيل نهائيًا نتائج الأدوات الأقدم إذا لزم الأمر. +- يفعّل `mode: "cache-ttl"` عمليات الاقتطاع. +- تتحكم `ttl` في عدد المرات التي يمكن بعدها تشغيل الاقتطاع مجدداً (بعد آخر لمسة للذاكرة المؤقتة). +- يقوم الاقتطاع أولاً باقتطاع نتائج الأدوات الكبيرة جزئياً، ثم يزيل بالكامل نتائج الأدوات الأقدم إذا لزم الأمر. -**الاقتطاع المرن** يحتفظ بالبداية + النهاية ويُدرج `...` في الوسط. +**الاقتطاع الجزئي** يحتفظ بالبداية + النهاية ويُدرج `...` في المنتصف. -**الإزالة النهائية** تستبدل نتيجة الأداة بالكامل بالنص النائب. +**الإزالة الكاملة** تستبدل نتيجة الأداة بالكامل بالنص البديل. ملاحظات: -- لا يتم اقتطاع/إزالة كتل الصور مطلقًا. -- تعتمد النسب على عدد الأحرف (تقريبية)، وليست على عدد الرموز بدقة. -- إذا كان عدد رسائل المساعد أقل من `keepLastAssistants`، يتم تخطي التقليم. +- لا يتم اقتطاع/إزالة كتل الصور أبداً. +- تعتمد النسب على عدد الأحرف (تقريبياً)، لا على عدد الرموز الدقيق. +- إذا كان عدد رسائل المساعد أقل من `keepLastAssistants`، يتم تخطي الاقتطاع. -راجع [Session Pruning](/ar/concepts/session-pruning) للحصول على تفاصيل السلوك. +راجع [Session Pruning](/ar/concepts/session-pruning) لمعرفة تفاصيل السلوك. -### البث على شكل كتل +### حظر البث ```json5 { @@ -1346,11 +1346,11 @@ Codex app-server harness المضمّن. } ``` -- تتطلب القنوات غير Telegram تعيين `*.blockStreaming: true` صراحة لتفعيل الردود على شكل كتل. -- تجاوزات القنوات: `channels..blockStreamingCoalesce` (ومتغيراتها لكل حساب). وتستخدم Signal/Slack/Discord/Google Chat افتراضيًا `minChars: 1500`. -- `humanDelay`: توقف عشوائي بين الردود الكتلية. تعني `natural` = ‏800–2500 مللي ثانية. التجاوز لكل وكيل: `agents.list[].humanDelay`. +- تتطلب القنوات غير Telegram تعيين `*.blockStreaming: true` صراحةً لتفعيل الردود المجمعة. +- تجاوزات القنوات: `channels..blockStreamingCoalesce` (ومتغيرات كل حساب). تكون القيم الافتراضية في Signal/Slack/Discord/Google Chat هي `minChars: 1500`. +- `humanDelay`: توقف عشوائي بين الردود المجمعة. تعني `natural` = ‏800–2500ms. تجاوز كل وكيل: `agents.list[].humanDelay`. -راجع [Streaming](/ar/concepts/streaming) للحصول على تفاصيل السلوك + التقسيم إلى كتل. +راجع [Streaming](/ar/concepts/streaming) لمعرفة تفاصيل السلوك + التقسيم إلى أجزاء. ### مؤشرات الكتابة @@ -1365,8 +1365,8 @@ Codex app-server harness المضمّن. } ``` -- القيم الافتراضية: `instant` للدردشات المباشرة/الإشارات، و`message` للدردشات الجماعية غير المذكور فيها. -- التجاوزات لكل جلسة: `session.typingMode` و`session.typingIntervalSeconds`. +- القيم الافتراضية: `instant` للمحادثات المباشرة/الإشارات، و`message` للمحادثات الجماعية غير المشار فيها. +- تجاوزات كل جلسة: `session.typingMode` و`session.typingIntervalSeconds`. راجع [Typing Indicators](/ar/concepts/typing-indicators). @@ -1374,7 +1374,7 @@ Codex app-server harness المضمّن. ### `agents.defaults.sandbox` -Sandbox اختياري للوكيل المضمّن. راجع [Sandboxing](/ar/gateway/sandboxing) للحصول على الدليل الكامل. +الحماية الاختيارية للوكيل المضمن. راجع [Sandboxing](/ar/gateway/sandboxing) للحصول على الدليل الكامل. ```json5 { @@ -1469,46 +1469,46 @@ Sandbox اختياري للوكيل المضمّن. راجع [Sandboxing](/ar/ga } ``` - + -**الخلفية:** +**الواجهة الخلفية:** - `docker`: وقت تشغيل Docker محلي (الافتراضي) -- `ssh`: وقت تشغيل بعيد عام مدعوم عبر SSH +- `ssh`: وقت تشغيل بعيد عام يعتمد على SSH - `openshell`: وقت تشغيل OpenShell عند تحديد `backend: "openshell"`، تنتقل الإعدادات الخاصة بوقت التشغيل إلى `plugins.entries.openshell.config`. -**إعدادات خلفية SSH:** +**إعداد الواجهة الخلفية SSH:** - `target`: هدف SSH بصيغة `user@host[:port]` - `command`: أمر عميل SSH (الافتراضي: `ssh`) - `workspaceRoot`: جذر بعيد مطلق يُستخدم لمساحات العمل بحسب النطاق -- `identityFile` / `certificateFile` / `knownHostsFile`: ملفات محلية موجودة مسبقًا تُمرَّر إلى OpenSSH +- `identityFile` / `certificateFile` / `knownHostsFile`: ملفات محلية موجودة يمررها OpenClaw إلى OpenSSH - `identityData` / `certificateData` / `knownHostsData`: محتويات مضمنة أو SecretRefs يقوم OpenClaw بتحويلها إلى ملفات مؤقتة وقت التشغيل -- `strictHostKeyChecking` / `updateHostKeys`: عناصر تحكم سياسة مفاتيح مضيف OpenSSH +- `strictHostKeyChecking` / `updateHostKeys`: مفاتيح سياسة مفتاح المضيف في OpenSSH **أسبقية مصادقة SSH:** - تتغلب `identityData` على `identityFile` - تتغلب `certificateData` على `certificateFile` - تتغلب `knownHostsData` على `knownHostsFile` -- يتم حل قيم `*Data` المدعومة بـ SecretRef من لقطة وقت تشغيل الأسرار النشطة قبل بدء جلسة Sandbox +- يتم حل قيم `*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` **النطاق:** @@ -1516,7 +1516,7 @@ Sandbox اختياري للوكيل المضمّن. راجع [Sandboxing](/ar/ga - `agent`: حاوية + مساحة عمل واحدة لكل وكيل (الافتراضي) - `shared`: حاوية ومساحة عمل مشتركتان (من دون عزل بين الجلسات) -**إعدادات plugin OpenShell:** +**إعداد OpenShell plugin:** ```json5 { @@ -1544,30 +1544,30 @@ Sandbox اختياري للوكيل المضمّن. راجع [Sandboxing](/ar/ga **وضع OpenShell:** -- `mirror`: يبذر البعيد من المحلي قبل exec، ثم يزامن عودةً بعد exec؛ وتظل مساحة العمل المحلية هي الأساسية -- `remote`: يبذر البعيد مرة واحدة عند إنشاء Sandbox، ثم يُبقي مساحة العمل البعيدة هي الأساسية +- `mirror`: زرع البعيد من المحلي قبل التنفيذ، ثم المزامنة العكسية بعد التنفيذ؛ وتبقى مساحة العمل المحلية هي النسخة المعتمدة +- `remote`: زرع البعيد مرة واحدة عند إنشاء sandbox، ثم إبقاء مساحة العمل البعيدة هي النسخة المعتمدة -في وضع `remote`، لا تتم مزامنة التعديلات المحلية على المضيف التي أُجريت خارج OpenClaw إلى Sandbox تلقائيًا بعد خطوة البذر. -يكون النقل عبر SSH إلى OpenShell sandbox، لكن plugin هو الذي يملك دورة حياة Sandbox ومزامنة mirror الاختيارية. +في وضع `remote`، لا تتم مزامنة التعديلات المحلية على المضيف التي تُجرى خارج OpenClaw إلى sandbox تلقائياً بعد خطوة الزرع. +يكون النقل عبر SSH إلى OpenShell sandbox، لكن الـ plugin يملك دورة حياة sandbox ومزامنة mirror الاختيارية. -**`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** (`sandbox.browser.enabled`): ‏Chromium + CDP داخل حاوية. يتم حقن عنوان noVNC URL في مطالبة النظام. ولا يتطلب `browser.enabled` في `openclaw.json`. -يستخدم وصول المراقبة عبر noVNC مصادقة VNC افتراضيًا، ويصدر OpenClaw عنوان URL برمز مميز قصير العمر (بدلًا من كشف كلمة المرور في عنوان URL المشترك). +**المتصفح المعزول** (`sandbox.browser.enabled`): ‏Chromium + CDP داخل حاوية. يتم حقن عنوان noVNC URL في مطالبة النظام. ولا يتطلب `browser.enabled` في `openclaw.json`. +يستخدم وصول المراقبة عبر noVNC مصادقة VNC افتراضياً ويصدر OpenClaw عنوان URL برمز مميز قصير العمر (بدلاً من كشف كلمة المرور في عنوان URL المشترك). -- يؤدي `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` وضبطها لمضيفي الحاويات: +- يؤدي `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` @@ -1584,28 +1584,28 @@ Sandbox اختياري للوكيل المضمّن. راجع [Sandboxing](/ar/ga - `--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/الرسوم ثلاثية الأبعاد يتطلب ذلك. + مفعلة افتراضياً ويمكن تعطيلها عبر + `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` إذا كان استخدام WebGL/3D يتطلب ذلك. - يعيد `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` تفعيل الإضافات إذا كان سير عملك يعتمد عليها. - - يمكن تغيير `--renderer-process-limit=2` باستخدام + - يمكن تغيير `--renderer-process-limit=2` عبر `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`؛ اضبطه على `0` لاستخدام - حد العمليات الافتراضي في Chromium. - - بالإضافة إلى `--no-sandbox` و`--disable-setuid-sandbox` عندما يكون `noSandbox` مفعّلًا. - - تمثل القيم الافتراضية خط الأساس لصورة الحاوية؛ استخدم صورة متصفح مخصصة مع + الحد الافتراضي للعمليات في Chromium. + - بالإضافة إلى `--no-sandbox` و`--disable-setuid-sandbox` عندما تكون `noSandbox` مفعلة. + - تمثل القيم الافتراضية خط أساس صورة الحاوية؛ استخدم صورة متصفح مخصصة مع entrypoint مخصص لتغيير القيم الافتراضية للحاوية. -يقتصر Sandboxing المتصفح و`sandbox.docker.binds` على Docker فقط. +يقتصر عزل المتصفح و`sandbox.docker.binds` على Docker فقط. أنشئ الصور: ```bash -scripts/sandbox-setup.sh # main sandbox image -scripts/sandbox-browser-setup.sh # optional browser image +scripts/sandbox-setup.sh # صورة sandbox الرئيسية +scripts/sandbox-browser-setup.sh # صورة المتصفح الاختيارية ``` ### `agents.list` (تجاوزات لكل وكيل) @@ -1658,20 +1658,20 @@ scripts/sandbox-browser-setup.sh # optional browser image ``` - `id`: معرّف وكيل ثابت (مطلوب). -- `default`: عند تعيين أكثر من وكيل، يفوز الأول (ويُسجَّل تحذير). وإذا لم يتم تعيين أي واحد، يكون أول إدخال في القائمة هو الافتراضي. -- `model`: يتجاوز شكل السلسلة قيمة `primary` فقط؛ بينما يتجاوز شكل الكائن `{ primary, fallbacks }` كليهما (`[]` يعطّل القيم الاحتياطية العامة). وتظل مهام Cron التي تتجاوز `primary` فقط ترث القيم الاحتياطية الافتراضية ما لم تعيّن `fallbacks: []`. -- `params`: معاملات تدفق لكل وكيل تُدمج فوق إدخال النموذج المحدد في `agents.defaults.models`. استخدم هذا من أجل تجاوزات خاصة بالوكيل مثل `cacheRetention` أو `temperature` أو `maxTokens` من دون تكرار فهرس النماذج بالكامل. -- `skills`: قائمة سماح اختيارية لـ Skills لكل وكيل. وإذا حُذفت، يرث الوكيل `agents.defaults.skills` عند تعيينها؛ وتستبدل القائمة الصريحة القيم الافتراضية بدلًا من الدمج، و`[]` تعني عدم استخدام أي Skills. +- `default`: عند تعيين أكثر من واحد، يفوز الأول (مع تسجيل تحذير). وإذا لم يُعيَّن أي واحد، يكون أول إدخال في القائمة هو الافتراضي. +- `model`: يتجاوز الشكل النصي `primary` فقط؛ بينما يتجاوز شكل الكائن `{ primary, fallbacks }` كليهما (`[]` يعطّل القيم الاحتياطية العامة). وظائف Cron التي لا تتجاوز سوى `primary` تستمر في وراثة القيم الاحتياطية الافتراضية ما لم تضبط `fallbacks: []`. +- `params`: معاملات بث لكل وكيل تُدمج فوق إدخال النموذج المحدد في `agents.defaults.models`. استخدم هذا للتجاوزات الخاصة بالوكيل مثل `cacheRetention` أو `temperature` أو `maxTokens` من دون تكرار فهرس النماذج بالكامل. +- `skills`: قائمة سماح اختيارية لـ Skills لكل وكيل. إذا حُذفت، يرث الوكيل `agents.defaults.skills` عند تعيينها؛ وتستبدل القائمة الصريحة القيم الافتراضية بدلاً من دمجها، وتعني `[]` عدم وجود Skills. - `thinkingDefault`: مستوى التفكير الافتراضي الاختياري لكل وكيل (`off | minimal | low | medium | high | xhigh | adaptive`). ويتجاوز `agents.defaults.thinkingDefault` لهذا الوكيل عندما لا يكون هناك تجاوز لكل رسالة أو جلسة. -- `reasoningDefault`: تجاوز اختياري لكل وكيل لرؤية reasoning (`on | off | stream`). ويُطبق عندما لا يكون هناك تجاوز لـ reasoning لكل رسالة أو جلسة. -- `fastModeDefault`: قيمة افتراضية اختيارية لكل وكيل لوضع السرعة (`true | false`). وتُطبق عندما لا يكون هناك تجاوز لوضع السرعة لكل رسالة أو جلسة. -- `embeddedHarness`: تجاوز اختياري لكل وكيل لسياسة harness منخفضة المستوى. استخدم `{ runtime: "codex", fallback: "none" }` لجعل أحد الوكلاء خاصًا بـ Codex فقط بينما يحتفظ الوكلاء الآخرون بخيار PI الاحتياطي الافتراضي. -- `runtime`: واصف وقت تشغيل اختياري لكل وكيل. استخدم `type: "acp"` مع القيم الافتراضية في `runtime.acp` (`agent` و`backend` و`mode` و`cwd`) عندما ينبغي أن يستخدم الوكيل جلسات ACP harness افتراضيًا. -- `identity.avatar`: مسار نسبي لمساحة العمل، أو `http(s)` URL، أو `data:` URI. -- تستنتج `identity` القيم الافتراضية: `ackReaction` من `emoji`، و`mentionPatterns` من `name`/`emoji`. -- `subagents.allowAgents`: قائمة سماح لمعرّفات الوكلاء من أجل `sessions_spawn` (`["*"]` = أي وكيل؛ الافتراضي: الوكيل نفسه فقط). -- حاجز وراثة Sandbox: إذا كانت جلسة الطالب داخل Sandbox، فإن `sessions_spawn` يرفض الأهداف التي ستعمل خارج Sandbox. -- `subagents.requireAgentId`: عند تعيينه إلى true، يمنع استدعاءات `sessions_spawn` التي تحذف `agentId` (يفرض اختيار ملف تعريف صريح؛ الافتراضي: false). +- `reasoningDefault`: تجاوز اختياري لكل وكيل لرؤية الاستدلال (`on | off | stream`). ويُطبّق عندما لا يكون هناك تجاوز للاستدلال لكل رسالة أو جلسة. +- `fastModeDefault`: القيمة الافتراضية الاختيارية لكل وكيل للوضع السريع (`true | false`). وتُطبّق عندما لا يكون هناك تجاوز للوضع السريع لكل رسالة أو جلسة. +- `embeddedHarness`: تجاوز اختياري لسياسة harness منخفض المستوى لكل وكيل. استخدم `{ runtime: "codex", fallback: "none" }` لجعل أحد الوكلاء مخصصاً لـ Codex فقط بينما يحتفظ الآخرون برجوع PI الافتراضي. +- `runtime`: واصف وقت تشغيل اختياري لكل وكيل. استخدم `type: "acp"` مع قيم `runtime.acp` الافتراضية (`agent` و`backend` و`mode` و`cwd`) عندما يجب أن يستخدم الوكيل جلسات ACP harness افتراضياً. +- `identity.avatar`: مسار نسبي لمساحة العمل، أو URL من نوع `http(s)`، أو URI من نوع `data:`. +- تستنتج `identity` قيماً افتراضية: `ackReaction` من `emoji`، و`mentionPatterns` من `name`/`emoji`. +- `subagents.allowAgents`: قائمة سماح لمعرّفات الوكلاء لـ `sessions_spawn` (`["*"]` = أي وكيل؛ الافتراضي: الوكيل نفسه فقط). +- حارس وراثة sandbox: إذا كانت جلسة الطالب داخل sandbox، يرفض `sessions_spawn` الأهداف التي ستعمل خارج sandbox. +- `subagents.requireAgentId`: عندما تكون true، يحظر استدعاءات `sessions_spawn` التي تحذف `agentId` (يفرض اختيار ملف شخصي صريح؛ الافتراضي: false). --- @@ -1696,29 +1696,29 @@ scripts/sandbox-browser-setup.sh # optional browser image ### حقول مطابقة الارتباط -- `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 }` +- `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`. -بالنسبة إلى إدخالات `type: "acp"`، يقوم OpenClaw بالحل وفق هوية المحادثة الدقيقة (`match.channel` + الحساب + `match.peer.id`) ولا يستخدم ترتيب مستويات route binding المذكور أعلاه. +بالنسبة إلى إدخالات `type: "acp"`، يجري OpenClaw الحل وفق هوية المحادثة الدقيقة (`match.channel` + الحساب + `match.peer.id`) ولا يستخدم ترتيب مستويات route binding أعلاه. -### ملفات تعريف الوصول لكل وكيل +### ملفات الوصول لكل وكيل - + ```json5 { @@ -1811,7 +1811,7 @@ scripts/sandbox-browser-setup.sh # optional browser image -راجع [Multi-Agent Sandbox & Tools](/ar/tools/multi-agent-sandbox-tools) للحصول على تفاصيل الأسبقية. +راجع [Multi-Agent Sandbox & Tools](/ar/tools/multi-agent-sandbox-tools) لمعرفة تفاصيل الأسبقية. --- @@ -1864,35 +1864,35 @@ scripts/sandbox-browser-setup.sh # optional browser image -- **`scope`**: إستراتيجية تجميع الجلسات الأساسية لسياقات الدردشة الجماعية. +- **`scope`**: استراتيجية تجميع الجلسات الأساسية لسياقات الدردشة الجماعية. - `per-sender` (الافتراضي): يحصل كل مرسل على جلسة معزولة داخل سياق القناة. - - `global`: يشترك جميع المشاركين في سياق القناة في جلسة واحدة (استخدمه فقط عندما يكون السياق المشترك مقصودًا). + - `global`: يشترك جميع المشاركين في سياق القناة في جلسة واحدة (استخدمه فقط عندما يكون السياق المشترك مقصوداً). - **`dmScope`**: كيفية تجميع الرسائل الخاصة. - - `main`: تشترك جميع الرسائل الخاصة في الجلسة الرئيسية. - - `per-peer`: العزل حسب معرّف المرسل عبر القنوات. - - `per-channel-peer`: العزل لكل قناة + مرسل (موصى به لصناديق الوارد متعددة المستخدمين). - - `per-account-channel-peer`: العزل لكل حساب + قناة + مرسل (موصى به للحسابات المتعددة). -- **`identityLinks`**: يربط المعرّفات القياسية بالنظراء ذوي بادئة الموفر لمشاركة الجلسات عبر القنوات. -- **`reset`**: سياسة إعادة التعيين الأساسية. يعيد `daily` التعيين عند `atHour` بالتوقيت المحلي؛ ويعيد `idle` التعيين بعد `idleMinutes`. وعند إعداد الاثنين، يفوز ما تنتهي صلاحيته أولًا. -- **`resetByType`**: تجاوزات حسب النوع (`direct` و`group` و`thread`). ويُقبل `dm` القديم كاسم مستعار لـ `direct`. -- **`parentForkMaxTokens`**: الحد الأقصى لـ `totalTokens` المسموح به في الجلسة الأم عند إنشاء جلسة سلسلة متفرعة (الافتراضي `100000`). - - إذا كانت قيمة `totalTokens` في الأصل أعلى من هذه القيمة، يبدأ OpenClaw جلسة سلسلة جديدة بدلًا من وراثة سجل محادثة الأصل. - - عيّن `0` لتعطيل هذا الحاجز والسماح دائمًا بالتفرع من الأصل. -- **`mainKey`**: حقل قديم. يستخدم وقت التشغيل دائمًا `"main"` لدلو الدردشة المباشرة الرئيسي. -- **`agentToAgent.maxPingPongTurns`**: الحد الأقصى لعدد أدوار الرد المتبادل بين الوكلاء أثناء تبادلات وكيل إلى وكيل (عدد صحيح، النطاق: `0`–`5`). تؤدي القيمة `0` إلى تعطيل سلسلة ping-pong. -- **`sendPolicy`**: المطابقة حسب `channel` أو `chatType` (`direct|group|channel`، مع الاسم المستعار القديم `dm`) أو `keyPrefix` أو `rawKeyPrefix`. أول تطابق للمنع هو الذي يفوز. + - `main`: تشترك كل الرسائل الخاصة في الجلسة الرئيسية. + - `per-peer`: عزل حسب معرّف المرسل عبر القنوات. + - `per-channel-peer`: عزل لكل قناة + مرسل (موصى به لصناديق الوارد متعددة المستخدمين). + - `per-account-channel-peer`: عزل لكل حساب + قناة + مرسل (موصى به لتعدد الحسابات). +- **`identityLinks`**: يربط المعرّفات القياسية بنظراء مسبوقين بالموفّر لمشاركة الجلسات عبر القنوات. +- **`reset`**: سياسة إعادة التعيين الأساسية. تعيد `daily` التعيين عند `atHour` حسب التوقيت المحلي؛ وتعيد `idle` التعيين بعد `idleMinutes`. وعند ضبط الاثنين معاً، يفوز أيهما تنتهي صلاحيته أولاً. +- **`resetByType`**: تجاوزات لكل نوع (`direct` و`group` و`thread`). وتُقبل القيمة القديمة `dm` كاسم مستعار لـ `direct`. +- **`parentForkMaxTokens`**: الحد الأقصى لقيمة `totalTokens` في الجلسة الأصلية المسموح بها عند إنشاء جلسة خيط متفرعة (الافتراضي `100000`). + - إذا كانت قيمة `totalTokens` في الجلسة الأصلية أعلى من هذه القيمة، يبدأ OpenClaw جلسة خيط جديدة بدلاً من وراثة سجل الجلسة الأصلية. + - اضبطها على `0` لتعطيل هذا الحارس والسماح دائماً بالتفريع من الأصل. +- **`mainKey`**: حقل قديم. يستخدم وقت التشغيل دائماً `"main"` لحاوية الدردشة المباشرة الرئيسية. +- **`agentToAgent.maxPingPongTurns`**: الحد الأقصى لأدوار الرد المتبادل بين الوكلاء أثناء تبادلات وكيل-إلى-وكيل (عدد صحيح، النطاق: `0`–`5`). تؤدي القيمة `0` إلى تعطيل التسلسل المتبادل. +- **`sendPolicy`**: المطابقة حسب `channel` أو `chatType` (`direct|group|channel`، مع الاسم المستعار القديم `dm`) أو `keyPrefix` أو `rawKeyPrefix`. ويفوز أول منع. - **`maintenance`**: عناصر تحكم تنظيف مخزن الجلسات + الاحتفاظ. - - `mode`: يؤدي `warn` إلى إصدار تحذيرات فقط؛ بينما يطبق `enforce` التنظيف. - - `pruneAfter`: حد العمر لإزالة الإدخالات القديمة (الافتراضي `30d`). + - `mode`: تصدر `warn` تحذيرات فقط؛ بينما تطبق `enforce` التنظيف. + - `pruneAfter`: حد العمر للإدخالات الراكدة (الافتراضي `30d`). - `maxEntries`: الحد الأقصى لعدد الإدخالات في `sessions.json` (الافتراضي `500`). - - `rotateBytes`: تدوير `sessions.json` عندما يتجاوز هذا الحجم (الافتراضي `10mb`). - - `resetArchiveRetention`: مدة الاحتفاظ بأرشيفات النصوص `*.reset.`. وتكون قيمته الافتراضية هي `pruneAfter`؛ عيّنه إلى `false` للتعطيل. - - `maxDiskBytes`: ميزانية قرص اختيارية لدليل الجلسات. في وضع `warn` يسجل تحذيرات؛ وفي وضع `enforce` يزيل أقدم المصنوعات/الجلسات أولًا. - - `highWaterBytes`: هدف اختياري بعد تنظيف الميزانية. قيمته الافتراضية `80%` من `maxDiskBytes`. -- **`threadBindings`**: القيم الافتراضية العامة لميزات الجلسات المرتبطة بالسلاسل. - - `enabled`: مفتاح افتراضي رئيسي (يمكن للموفرين تجاوزه؛ ويستخدم Discord القيمة `channels.discord.threadBindings.enabled`) - - `idleHours`: الإلغاء التلقائي الافتراضي للتركيز بعد عدم النشاط بالساعات (`0` للتعطيل؛ ويمكن للموفرين تجاوزه) - - `maxAgeHours`: الحد الأقصى الصارم الافتراضي للعمر بالساعات (`0` للتعطيل؛ ويمكن للموفرين تجاوزه) + - `rotateBytes`: تدوير `sessions.json` عند تجاوزه هذا الحجم (الافتراضي `10mb`). + - `resetArchiveRetention`: مدة الاحتفاظ بأرشيفات النصوص `*.reset.`. وتعود افتراضياً إلى `pruneAfter`؛ واضبطها على `false` للتعطيل. + - `maxDiskBytes`: ميزانية قرص اختيارية لدليل الجلسات. في وضع `warn` تسجل تحذيرات؛ وفي وضع `enforce` تزيل أقدم العناصر/الجلسات أولاً. + - `highWaterBytes`: الهدف الاختياري بعد تنظيف الميزانية. ويكون افتراضياً `80%` من `maxDiskBytes`. +- **`threadBindings`**: القيم الافتراضية العامة لميزات الجلسات المرتبطة بالخيوط. + - `enabled`: مفتاح افتراضي رئيسي (يمكن للموفّرين تجاوزه؛ ويستخدم Discord القيمة `channels.discord.threadBindings.enabled`) + - `idleHours`: إلغاء التركيز التلقائي الافتراضي بعد عدم النشاط بالساعات (`0` يعطّل ذلك؛ ويمكن للموفّرين تجاوزه) + - `maxAgeHours`: الحد الأقصى الصارم الافتراضي للعمر بالساعات (`0` يعطّل ذلك؛ ويمكن للموفّرين تجاوزه) @@ -1932,34 +1932,34 @@ scripts/sandbox-browser-setup.sh # optional browser image تجاوزات لكل قناة/حساب: `channels..responsePrefix` و`channels..accounts..responsePrefix`. -آلية الحل (الأكثر تحديدًا يفوز): الحساب ← القناة ← العام. تؤدي القيمة `""` إلى التعطيل وإيقاف التسلسل. وتؤدي `"auto"` إلى اشتقاق `[{identity.name}]`. +آلية الحل (الأكثر تحديداً يفوز): الحساب ← القناة ← العام. تعطل `""` الميزة وتوقف التسلسل. تستنتج `"auto"` القيمة `[{identity.name}]`. **متغيرات القالب:** -| المتغير | الوصف | المثال | -| ------- | ----- | ------ | -| `{model}` | اسم النموذج المختصر | `claude-opus-4-6` | -| `{modelFull}` | معرّف النموذج الكامل | `anthropic/claude-opus-4-6` | -| `{provider}` | اسم الموفر | `anthropic` | -| `{thinkingLevel}` | مستوى التفكير الحالي | `high` و`low` و`off` | -| `{identity.name}` | اسم هوية الوكيل | (مثل `"auto"`) | +| المتغير | الوصف | المثال | +| ----------------- | ---------------------- | --------------------------- | +| `{model}` | الاسم المختصر للنموذج | `claude-opus-4-6` | +| `{modelFull}` | معرّف النموذج الكامل | `anthropic/claude-opus-4-6` | +| `{provider}` | اسم الموفّر | `anthropic` | +| `{thinkingLevel}` | مستوى التفكير الحالي | `high`، `low`، `off` | +| `{identity.name}` | اسم هوية الوكيل | (مثل `"auto"`) | -المتغيرات غير حساسة لحالة الأحرف. ويُعد `{think}` اسمًا مستعارًا لـ `{thinkingLevel}`. +المتغيرات غير حساسة لحالة الأحرف. وتمثل `{think}` اسماً مستعاراً لـ `{thinkingLevel}`. -### تفاعل التأكيد +### تفاعل الإقرار -- تكون قيمته الافتراضية `identity.emoji` الخاصة بالوكيل النشط، وإلا `"👀"`. عيّن `""` للتعطيل. +- يعود افتراضياً إلى `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` لتفعيل تفاعلات حالة دورة الحياة. +- ترتيب الحل: الحساب ← القناة ← `messages.ackReaction` ← الرجوع إلى الهوية. +- النطاق: `group-mentions` (الافتراضي)، و`group-all`، و`direct`، و`all`. +- يزيل `removeAckAfterReply` تفاعل الإقرار بعد الرد في Slack وDiscord وTelegram. +- يفعّل `messages.statusReactions.enabled` تفاعلات الحالة المرتبطة بدورة الحياة في Slack وDiscord وTelegram. + في Slack وDiscord، يؤدي تركه غير مضبوط إلى إبقاء تفاعلات الحالة مفعلة عندما تكون تفاعلات الإقرار نشطة. + وفي Telegram، اضبطه صراحةً على `true` لتمكين تفاعلات الحالة المرتبطة بدورة الحياة. -### إزالة الارتداد للرسائل الواردة +### إزالة الارتداد للوارد -يجمع الرسائل النصية السريعة فقط من المرسل نفسه في دور وكيل واحد. ويتم تفريغ الوسائط/المرفقات فورًا. وتتجاوز أوامر التحكم إزالة الارتداد. +يجمع الرسائل النصية السريعة من المرسل نفسه في دور وكيل واحد. وتؤدي الوسائط/المرفقات إلى التفريغ فوراً. وتتجاوز أوامر التحكم إزالة الارتداد. ### TTS (تحويل النص إلى كلام) @@ -2002,12 +2002,12 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- يتحكم `auto` في وضع TTS التلقائي الافتراضي: `off` أو `always` أو `inbound` أو `tagged`. ويمكن لـ `/tts on|off` تجاوز التفضيلات المحلية، ويعرض `/tts status` الحالة الفعلية. -- يتجاوز `summaryModel` قيمة `agents.defaults.model.primary` للملخص التلقائي. -- تكون `modelOverrides` مفعّلة افتراضيًا؛ وتكون القيمة الافتراضية لـ `modelOverrides.allowProvider` هي `false` (اشتراك اختياري). -- تعود مفاتيح API احتياطيًا إلى `ELEVENLABS_API_KEY`/`XI_API_KEY` و`OPENAI_API_KEY`. -- يتجاوز `openai.baseUrl` نقطة نهاية TTS الخاصة بـ OpenAI. ترتيب الحل هو الإعدادات، ثم `OPENAI_TTS_BASE_URL`، ثم `https://api.openai.com/v1`. -- عندما يشير `openai.baseUrl` إلى نقطة نهاية ليست لـ OpenAI، يتعامل OpenClaw معها بوصفها خادم TTS متوافقًا مع OpenAI ويخفف التحقق من النموذج/الصوت. +- يتحكم `auto` في وضع TTS التلقائي الافتراضي: `off` أو `always` أو `inbound` أو `tagged`. ويمكن للأمر `/tts on|off` تجاوز التفضيلات المحلية، ويعرض `/tts status` الحالة الفعلية. +- يتجاوز `summaryModel` القيمة `agents.defaults.model.primary` للملخص التلقائي. +- تكون `modelOverrides` مفعلة افتراضياً؛ وتكون القيمة الافتراضية لـ `modelOverrides.allowProvider` هي `false` (تفعيل اختياري). +- تعود مفاتيح API إلى `ELEVENLABS_API_KEY`/`XI_API_KEY` و`OPENAI_API_KEY`. +- يتجاوز `openai.baseUrl` نقطة نهاية OpenAI TTS. ترتيب الحل هو: الإعدادات، ثم `OPENAI_TTS_BASE_URL`، ثم `https://api.openai.com/v1`. +- عندما يشير `openai.baseUrl` إلى نقطة نهاية ليست لـ OpenAI، يتعامل OpenClaw معها على أنها خادم TTS متوافق مع OpenAI ويخفف التحقق من النموذج/الصوت. --- @@ -2037,13 +2037,13 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- يجب أن يطابق `talk.provider` مفتاحًا في `talk.providers` عند إعداد عدة موفري Talk. -- مفاتيح Talk المسطحة القديمة (`talk.voiceId` و`talk.voiceAliases` و`talk.modelId` و`talk.outputFormat` و`talk.apiKey`) مخصصة للتوافق فقط ويتم ترحيلها تلقائيًا إلى `talk.providers.`. -- تعود معرّفات الأصوات احتياطيًا إلى `ELEVENLABS_VOICE_ID` أو `SAG_VOICE_ID`. -- يقبل `providers.*.apiKey` سلاسل نصية صريحة أو كائنات SecretRef. -- لا يُطبَّق الاحتياطي `ELEVENLABS_API_KEY` إلا عندما لا يكون هناك مفتاح API مُعد لـ Talk. -- يتيح `providers.*.voiceAliases` لتوجيهات Talk استخدام أسماء ودية. -- يتحكم `silenceTimeoutMs` في مدة انتظار وضع Talk بعد صمت المستخدم قبل إرسال النص المفرغ. ويؤدي عدم تعيينه إلى الإبقاء على نافذة التوقف الافتراضية الخاصة بالمنصة (`700 ms على macOS وAndroid، و`900 ms` على iOS). +- يجب أن تطابق `talk.provider` مفتاحاً في `talk.providers` عندما يتم إعداد عدة موفّري Talk. +- مفاتيح Talk المسطحة القديمة (`talk.voiceId` و`talk.voiceAliases` و`talk.modelId` و`talk.outputFormat` و`talk.apiKey`) مخصصة للتوافق فقط، وتُرحّل تلقائياً إلى `talk.providers.`. +- تعود معرّفات الصوت إلى `ELEVENLABS_VOICE_ID` أو `SAG_VOICE_ID`. +- تقبل `providers.*.apiKey` سلاسل نصية صريحة أو كائنات SecretRef. +- لا يُستخدم البديل `ELEVENLABS_API_KEY` إلا عندما لا يكون هناك مفتاح API مُعدّ لـ Talk. +- تسمح `providers.*.voiceAliases` لتوجيهات Talk باستخدام أسماء سهلة. +- تتحكم `silenceTimeoutMs` في المدة التي ينتظرها وضع Talk بعد صمت المستخدم قبل إرسال النص المنسوخ. وتركها غير معيّنة يبقي نافذة التوقف الافتراضية الخاصة بالمنصة (`700 ms` على macOS وAndroid، و`900 ms` على iOS). --- @@ -2051,22 +2051,22 @@ scripts/sandbox-browser-setup.sh # optional browser image ### ملفات تعريف الأدوات -يحدد `tools.profile` قائمة سماح أساسية قبل `tools.allow`/`tools.deny`: +يضبط `tools.profile` قائمة السماح الأساسية قبل `tools.allow`/`tools.deny`: -تضبط عملية onboarding المحلية الإعدادات المحلية الجديدة افتراضيًا على `tools.profile: "coding"` عند عدم تعيينه (وتُحفظ ملفات التعريف الصريحة الحالية). +تضبط عملية الإعداد المحلي الإعدادات المحلية الجديدة افتراضياً على `tools.profile: "coding"` عند عدم تعيينه (مع الحفاظ على الملفات التعريفية الصريحة الحالية). -| ملف التعريف | يتضمن | -| ----------- | ------- | +| الملف التعريفي | يتضمن | +| ----------- | ------------------------------------------------------------------------------------------------------------------------------- | | `minimal` | `session_status` فقط | | `coding` | `group:fs` و`group:runtime` و`group:web` و`group:sessions` و`group:memory` و`cron` و`image` و`image_generate` و`video_generate` | | `messaging` | `group:messaging` و`sessions_list` و`sessions_history` و`sessions_send` و`session_status` | -| `full` | بلا تقييد (مثل غير المعيّن) | +| `full` | بلا تقييد (مماثل لعدم التعيين) | ### مجموعات الأدوات -| المجموعة | الأدوات | -| -------- | ------- | -| `group:runtime` | `exec` و`process` و`code_execution` (يُقبل `bash` كاسم مستعار لـ `exec`) | +| المجموعة | الأدوات | +| ------------------ | ----------------------------------------------------------------------------------------------------------------------- | +| `group:runtime` | `exec` و`process` و`code_execution` (`bash` مقبول كاسم مستعار لـ `exec`) | | `group:fs` | `read` و`write` و`edit` و`apply_patch` | | `group:sessions` | `sessions_list` و`sessions_history` و`sessions_send` و`sessions_spawn` و`sessions_yield` و`subagents` و`session_status` | | `group:memory` | `memory_search` و`memory_get` | @@ -2077,469 +2077,1100 @@ scripts/sandbox-browser-setup.sh # optional browser image | `group:nodes` | `nodes` | | `group:agents` | `agents_list` | | `group:media` | `image` و`image_generate` و`video_generate` و`tts` | -| `group:openclaw` | جميع الأدوات المضمّنة (باستثناء provider plugins) | +| `group:openclaw` | جميع الأدوات المضمنة (باستثناء provider plugins) | ### `tools.allow` / `tools.deny` -سياسة السماح/المنع العامة للأدوات (المنع يفوز). غير حساسة لحالة الأحرف، وتدعم أحرف البدل `*`. وتُطبق حتى عندما يكون Docker sandbox معطلًا. -__OC_I18N_900053__ +سياسة السماح/المنع العامة للأدوات (المنع يفوز). غير حساسة لحالة الأحرف، وتدعم أحرف البدل `*`. وتُطبق حتى عندما يكون Docker sandbox معطلاً. + +```json5 +{ + tools: { deny: ["browser", "canvas"] }, +} +``` + ### `tools.byProvider` -تفرض قيودًا إضافية على الأدوات لموفرين أو نماذج محددة. الترتيب: ملف التعريف الأساسي ← ملف تعريف الموفر ← السماح/المنع. -__OC_I18N_900054__ +تقيّد الأدوات أكثر لموفّرين أو نماذج محددة. الترتيب: الملف التعريفي الأساسي ← ملف تعريف الموفّر ← السماح/المنع. + +```json5 +{ + tools: { + profile: "coding", + byProvider: { + "google-antigravity": { profile: "minimal" }, + "openai/gpt-5.4": { allow: ["group:fs", "sessions_list"] }, + }, + }, +} +``` + ### `tools.elevated` -يتحكم في وصول exec المرتفع خارج Sandbox: -__OC_I18N_900055__ -- لا يمكن للتجاوز لكل وكيل (`agents.list[].tools.elevated`) إلا أن يفرض مزيدًا من التقييد. -- يخزن `/elevated on|off|ask|full` الحالة لكل جلسة؛ وتُطبق التوجيهات المضمنة على رسالة واحدة. -- يتجاوز `exec` المرتفع Sandboxing ويستخدم مسار الهروب المُعد (`gateway` افتراضيًا، أو `node` عندما يكون هدف exec هو `node`). +يتحكم في وصول exec المرتفع خارج sandbox: + +```json5 +{ + tools: { + elevated: { + enabled: true, + allowFrom: { + whatsapp: ["+15555550123"], + discord: ["1234567890123", "987654321098765432"], + }, + }, + }, +} +``` + +- لا يمكن للتجاوز لكل وكيل (`agents.list[].tools.elevated`) إلا أن يقيّد أكثر. +- يخزن `/elevated on|off|ask|full` الحالة لكل جلسة؛ بينما تطبق التوجيهات المضمنة على رسالة واحدة. +- يتجاوز `exec` المرتفع sandboxing ويستخدم مسار الإفلات المُعدّ (`gateway` افتراضياً، أو `node` عندما يكون هدف exec هو `node`). ### `tools.exec` -__OC_I18N_900056__ + +```json5 +{ + tools: { + exec: { + backgroundMs: 10000, + timeoutSec: 1800, + cleanupMs: 1800000, + notifyOnExit: true, + notifyOnExitEmptySuccess: false, + applyPatch: { + enabled: false, + allowModels: ["gpt-5.4"], + }, + }, + }, +} +``` + ### `tools.loopDetection` -تكون فحوصات أمان حلقات الأدوات **معطلة افتراضيًا**. عيّن `enabled: true` لتفعيل الكشف. -يمكن تعريف الإعدادات عمومًا في `tools.loopDetection` وتجاوزها لكل وكيل في `agents.list[].tools.loopDetection`. -__OC_I18N_900057__ -- `historySize`: الحد الأقصى لسجل استدعاءات الأدوات المحتفَظ به لتحليل الحلقات. -- `warningThreshold`: عتبة نمط التكرار بلا تقدم لإصدار التحذيرات. +تكون فحوصات أمان حلقات الأدوات **معطلة افتراضياً**. اضبط `enabled: true` لتفعيل الاكتشاف. +يمكن تعريف الإعدادات عالمياً في `tools.loopDetection` وتجاوزها لكل وكيل في `agents.list[].tools.loopDetection`. + +```json5 +{ + tools: { + loopDetection: { + enabled: true, + historySize: 30, + warningThreshold: 10, + criticalThreshold: 20, + globalCircuitBreakerThreshold: 30, + detectors: { + genericRepeat: true, + knownPollNoProgress: true, + pingPong: true, + }, + }, + }, +} +``` + +- `historySize`: الحد الأقصى لسجل استدعاءات الأدوات المحتفظ به لتحليل الحلقات. +- `warningThreshold`: عتبة نمط التكرار من دون تقدم لإصدار التحذيرات. - `criticalThreshold`: عتبة تكرار أعلى لحظر الحلقات الحرجة. - `globalCircuitBreakerThreshold`: عتبة إيقاف صارمة لأي تشغيل بلا تقدم. -- `detectors.genericRepeat`: يحذر عند تكرار استدعاءات الأداة نفسها/الوسائط نفسها. -- `detectors.knownPollNoProgress`: يحذر/يحظر أدوات الاستطلاع المعروفة (`process.poll` و`command_status` وما إلى ذلك) عند عدم وجود تقدم. -- `detectors.pingPong`: يحذر/يحظر أنماط الأزواج المتناوبة بلا تقدم. +- `detectors.genericRepeat`: التحذير عند تكرار استدعاءات نفس الأداة/نفس الوسائط. +- `detectors.knownPollNoProgress`: التحذير/الحظر عند أدوات الاستطلاع المعروفة (`process.poll` و`command_status` وما إلى ذلك). +- `detectors.pingPong`: التحذير/الحظر عند الأنماط الزوجية المتناوبة بلا تقدم. - إذا كانت `warningThreshold >= criticalThreshold` أو `criticalThreshold >= globalCircuitBreakerThreshold`، يفشل التحقق. ### `tools.web` -__OC_I18N_900058__ + +```json5 +{ + tools: { + web: { + search: { + enabled: true, + apiKey: "brave_api_key", // or BRAVE_API_KEY env + maxResults: 5, + timeoutSeconds: 30, + cacheTtlMinutes: 15, + }, + fetch: { + enabled: true, + provider: "firecrawl", // optional; omit for auto-detect + maxChars: 50000, + maxCharsCap: 50000, + maxResponseBytes: 2000000, + timeoutSeconds: 30, + cacheTtlMinutes: 15, + maxRedirects: 3, + readability: true, + userAgent: "custom-ua", + }, + }, + }, +} +``` + ### `tools.media` -يُعدّ فهم الوسائط الواردة (الصور/الصوت/الفيديو): -__OC_I18N_900059__ +يهيئ فهم الوسائط الواردة (الصورة/الصوت/الفيديو): + +```json5 +{ + tools: { + media: { + concurrency: 2, + asyncCompletion: { + directSend: false, // opt-in: send finished async music/video directly to the channel + }, + audio: { + enabled: true, + maxBytes: 20971520, + scope: { + default: "deny", + rules: [{ action: "allow", match: { chatType: "direct" } }], + }, + models: [ + { provider: "openai", model: "gpt-4o-mini-transcribe" }, + { type: "cli", command: "whisper", args: ["--model", "base", "{{MediaPath}}"] }, + ], + }, + video: { + enabled: true, + maxBytes: 52428800, + models: [{ provider: "google", model: "gemini-3-flash-preview" }], + }, + }, + }, +} +``` + -**إدخال الموفر** (`type: "provider"` أو عند حذفه): +**إدخال الموفّر** (`type: "provider"` أو عند الحذف): -- `provider`: معرّف موفر API (`openai` أو `anthropic` أو `google`/`gemini` أو `groq`، إلخ) +- `provider`: معرّف موفّر API (`openai` أو `anthropic` أو `google`/`gemini` أو `groq` وما إلى ذلك) - `model`: تجاوز معرّف النموذج -- `profile` / `preferredProfile`: اختيار ملف تعريف `auth-profiles.json` +- `profile` / `preferredProfile`: اختيار ملف `auth-profiles.json` **إدخال CLI** (`type: "cli"`): - `command`: الملف التنفيذي المراد تشغيله -- `args`: وسائط قالبية (تدعم `{{MediaPath}}` و`{{Prompt}}` و`{{MaxChars}}` وما إلى ذلك) +- `args`: وسائط مبنية على القوالب (تدعم `{{MediaPath}}` و`{{Prompt}}` و`{{MaxChars}}` وما إلى ذلك) **حقول مشتركة:** - `capabilities`: قائمة اختيارية (`image` و`audio` و`video`). القيم الافتراضية: `openai`/`anthropic`/`minimax` ← صورة، و`google` ← صورة+صوت+فيديو، و`groq` ← صوت. - `prompt` و`maxChars` و`maxBytes` و`timeoutSeconds` و`language`: تجاوزات لكل إدخال. -- تعود الإخفاقات احتياطيًا إلى الإدخال التالي. +- تعود حالات الفشل إلى الإدخال التالي. -تتبع مصادقة الموفر الترتيب القياسي: `auth-profiles.json` ← متغيرات البيئة ← `models.providers.*.apiKey`. +تتبع مصادقة الموفّر الترتيب القياسي: `auth-profiles.json` ← متغيرات البيئة ← `models.providers.*.apiKey`. **حقول الإكمال غير المتزامن:** -- عندما تكون `asyncCompletion.directSend` مساوية لـ `true`، تحاول المهام المكتملة غير المتزامنة الخاصة بـ `music_generate` - و`video_generate` التسليم المباشر إلى القناة أولًا. والقيمة الافتراضية: `false` - (مسار التنبيه/تسليم النموذج القديم الخاص بجلسة الطالب). +- `asyncCompletion.directSend`: عندما تكون `true`، تحاول مهام + `music_generate` و`video_generate` غير المتزامنة المكتملة التسليم المباشر + إلى القناة أولاً. الافتراضي: `false` + (مسار legacy requester-session wake/model-delivery). ### `tools.agentToAgent` -__OC_I18N_900060__ + +```json5 +{ + tools: { + agentToAgent: { + enabled: false, + allow: ["home", "work"], + }, + }, +} +``` + ### `tools.sessions` يتحكم في الجلسات التي يمكن استهدافها بواسطة أدوات الجلسات (`sessions_list` و`sessions_history` و`sessions_send`). الافتراضي: `tree` (الجلسة الحالية + الجلسات التي أنشأتها، مثل الوكلاء الفرعيين). -__OC_I18N_900061__ + +```json5 +{ + tools: { + sessions: { + // "self" | "tree" | "agent" | "all" + visibility: "tree", + }, + }, +} +``` + ملاحظات: - `self`: مفتاح الجلسة الحالية فقط. - `tree`: الجلسة الحالية + الجلسات التي أنشأتها الجلسة الحالية (الوكلاء الفرعيون). -- `agent`: أي جلسة تابعة لمعرّف الوكيل الحالي (قد يشمل مستخدمين آخرين إذا كنت تشغل جلسات per-sender تحت معرّف الوكيل نفسه). -- `all`: أي جلسة. وما يزال الاستهداف عبر الوكلاء يتطلب `tools.agentToAgent`. -- تقييد Sandbox: عندما تكون الجلسة الحالية داخل Sandbox ويكون `agents.defaults.sandbox.sessionToolsVisibility="spawned"`، تُفرض `visibility` على `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`. -__OC_I18N_900062__ + +```json5 +{ + tools: { + sessions_spawn: { + attachments: { + 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 per file + retainOnSessionKeep: false, // keep attachments when cleanup="keep" + }, + }, + }, +} +``` + ملاحظات: -- لا تُدعم المرفقات إلا مع `runtime: "subagent"`. ويرفض وقت تشغيل ACP هذه المرفقات. -- تُنشأ الملفات فعليًا داخل مساحة عمل الطفل في `.openclaw/attachments//` مع ملف `.manifest.json`. -- يتم تلقائيًا إخفاء محتوى المرفقات من حفظ السجل. -- يتم التحقق من مدخلات Base64 باستخدام فحوصات صارمة للأبجدية/الحشو وحاجز حجم قبل فك الترميز. +- المرفقات مدعومة فقط لـ `runtime: "subagent"`. ويرفض وقت تشغيل ACP هذه المرفقات. +- تُحوَّل الملفات إلى مساحة عمل الطفل ضمن `.openclaw/attachments//` مع ملف `.manifest.json`. +- يُحجب محتوى المرفقات تلقائياً من حفظ السجل. +- تُتحقق مدخلات Base64 باستخدام فحوصات صارمة للأبجدية/الحشو وحارس حجم قبل فك الترميز. - تكون أذونات الملفات `0700` للأدلة و`0600` للملفات. -- يتبع التنظيف سياسة `cleanup`: تؤدي `delete` دائمًا إلى إزالة المرفقات؛ وتؤدي `keep` إلى الاحتفاظ بها فقط عندما تكون `retainOnSessionKeep: true`. +- يتبع التنظيف سياسة `cleanup`: تؤدي `delete` دائماً إلى إزالة المرفقات؛ بينما تحتفظ `keep` بها فقط عندما تكون `retainOnSessionKeep: true`. ### `tools.experimental` -أعلام الأدوات المضمّنة التجريبية. تكون معطلة افتراضيًا ما لم تنطبق قاعدة تمكين تلقائي صارمة لـ GPT-5 agentic. -__OC_I18N_900063__ +أعلام الأدوات المضمنة التجريبية. تكون معطلة افتراضياً ما لم تنطبق قاعدة تمكين تلقائي صارمة لـ GPT-5 agentic. + +```json5 +{ + tools: { + experimental: { + planTool: true, // enable experimental update_plan + }, + }, +} +``` + ملاحظات: -- `planTool`: يفعّل أداة `update_plan` المهيكلة لتتبع الأعمال غير التافهة متعددة الخطوات. -- الافتراضي: `false` ما لم يتم تعيين `agents.defaults.embeddedPi.executionContract` (أو تجاوز لكل وكيل) إلى `"strict-agentic"` لتشغيل OpenAI أو OpenAI Codex من عائلة GPT-5. عيّنه إلى `true` لفرض تشغيل الأداة خارج هذا النطاق، أو إلى `false` لإبقائها معطلة حتى في تشغيلات GPT-5 strict-agentic. -- عند التفعيل، تضيف مطالبة النظام أيضًا إرشادات استخدام لكي لا يستخدمها النموذج إلا للأعمال الجوهرية، مع إبقاء خطوة واحدة فقط كحد أقصى في حالة `in_progress`. +- `planTool`: يفعّل أداة `update_plan` المنظمة لتتبع الأعمال متعددة الخطوات غير البسيطة. +- الافتراضي: `false` ما لم تكن `agents.defaults.embeddedPi.executionContract` (أو تجاوز لكل وكيل) مضبوطة على `"strict-agentic"` لتشغيل من عائلة OpenAI أو OpenAI Codex GPT-5. اضبطها على `true` لفرض تشغيل الأداة خارج هذا النطاق، أو على `false` لإبقائها معطلة حتى في تشغيلات GPT-5 الصارمة agentic. +- عند التفعيل، تضيف مطالبة النظام أيضاً إرشادات استخدام بحيث لا يستخدمها النموذج إلا في الأعمال الجوهرية ويحافظ على خطوة واحدة فقط بحالة `in_progress`. ### `agents.defaults.subagents` -__OC_I18N_900064__ -- `model`: النموذج الافتراضي للوكلاء الفرعيين الذين تم إنشاؤهم. وإذا حُذف، يرث الوكلاء الفرعيون نموذج المتصل. -- `allowAgents`: قائمة السماح الافتراضية لمعرّفات الوكلاء المستهدفين من أجل `sessions_spawn` عندما لا يعيّن الوكيل الطالب `subagents.allowAgents` الخاص به (`["*"]` = أي وكيل؛ الافتراضي: الوكيل نفسه فقط). -- `runTimeoutSeconds`: المهلة الافتراضية (بالثواني) لـ `sessions_spawn` عندما تحذف استدعاء الأداة `runTimeoutSeconds`. وتعني `0` عدم وجود مهلة. + +```json5 +{ + agents: { + defaults: { + subagents: { + allowAgents: ["research"], + model: "minimax/MiniMax-M2.7", + maxConcurrent: 8, + runTimeoutSeconds: 900, + archiveAfterMinutes: 60, + }, + }, + }, +} +``` + +- `model`: النموذج الافتراضي للوكلاء الفرعيين الذين يتم إنشاؤهم. وإذا حُذف، يرث الوكلاء الفرعيون نموذج المستدعي. +- `allowAgents`: قائمة السماح الافتراضية لمعرّفات الوكلاء المستهدفين من `sessions_spawn` عندما لا يضبط وكيل الطالب `subagents.allowAgents` الخاص به (`["*"]` = أي وكيل؛ الافتراضي: الوكيل نفسه فقط). +- `runTimeoutSeconds`: المهلة الافتراضية (بالثواني) لـ `sessions_spawn` عندما يحذف استدعاء الأداة `runTimeoutSeconds`. وتعني `0` عدم وجود مهلة. - سياسة الأدوات لكل وكيل فرعي: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. --- ## الموفّرون المخصصون وعناوين URL الأساسية -يستخدم OpenClaw فهرس النماذج المضمّن. أضف موفرين مخصصين عبر `models.providers` في الإعدادات أو `~/.openclaw/agents//agent/models.json`. -__OC_I18N_900065__ +يستخدم OpenClaw فهرس النماذج المضمّن. أضف موفّرين مخصصين عبر `models.providers` في الإعدادات أو `~/.openclaw/agents//agent/models.json`. + +```json5 +{ + models: { + mode: "merge", // merge (default) | replace + providers: { + "custom-proxy": { + baseUrl: "http://localhost:4000/v1", + apiKey: "LITELLM_KEY", + api: "openai-completions", // openai-completions | openai-responses | anthropic-messages | google-generative-ai + models: [ + { + id: "llama-3.1-8b", + name: "Llama 3.1 8B", + reasoning: false, + input: ["text"], + cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, + contextWindow: 128000, + contextTokens: 96000, + maxTokens: 32000, + }, + ], + }, + }, + }, +} +``` + - استخدم `authHeader: true` + `headers` لاحتياجات المصادقة المخصصة. -- تجاوز جذر إعدادات الوكيل باستخدام `OPENCLAW_AGENT_DIR` (أو `PI_CODING_AGENT_DIR`، وهو اسم مستعار قديم لمتغير البيئة). -- أسبقية الدمج لمعرّفات الموفرين المتطابقة: +- تجاوز جذر إعداد الوكيل عبر `OPENCLAW_AGENT_DIR` (أو `PI_CODING_AGENT_DIR`، وهو اسم مستعار قديم لمتغير بيئة). +- أسبقية الدمج لمعرّفات الموفّر المطابقة: - تفوز قيم `baseUrl` غير الفارغة في `models.json` الخاصة بالوكيل. - - تفوز قيم `apiKey` غير الفارغة الخاصة بالوكيل فقط عندما لا يكون ذلك الموفر مُدارًا عبر SecretRef في سياق الإعدادات/ملف تعريف المصادقة الحالي. - - يتم تحديث قيم `apiKey` الخاصة بالموفر المُدار عبر SecretRef من علامات المصدر (`ENV_VAR_NAME` لمراجع البيئة، و`secretref-managed` لمراجع الملف/exec) بدلًا من حفظ الأسرار المحلولة. - - يتم تحديث قيم رؤوس الموفر المُدارة عبر SecretRef من علامات المصدر (`secretref-env:ENV_VAR_NAME` لمراجع البيئة، و`secretref-managed` لمراجع الملف/exec). - - تعود قيم `apiKey`/`baseUrl` الفارغة أو المحذوفة من الوكيل احتياطيًا إلى `models.providers` في الإعدادات. - - تستخدم القيم المتطابقة للنموذج في `contextWindow`/`maxTokens` القيمة الأعلى بين الإعدادات الصريحة وقيم الفهرس الضمنية. - - تحافظ القيم المتطابقة للنموذج في `contextTokens` على حد وقت تشغيل صريح عندما يكون موجودًا؛ استخدمه لتقييد السياق الفعلي من دون تغيير بيانات النموذج الأصلية. + - تفوز قيم `apiKey` غير الفارغة الخاصة بالوكيل فقط عندما لا يكون ذلك الموفّر مُداراً عبر SecretRef في سياق الإعداد/ملف المصادقة الحالي. + - تُحدَّث قيم `apiKey` للموفّرين المُدارين عبر SecretRef من علامات المصدر (`ENV_VAR_NAME` لمراجع البيئة، و`secretref-managed` لمراجع الملف/التنفيذ) بدلاً من حفظ الأسرار المحلولة. + - تُحدَّث قيم رؤوس الموفّر المُدارة عبر SecretRef من علامات المصدر (`secretref-env:ENV_VAR_NAME` لمراجع البيئة، و`secretref-managed` لمراجع الملف/التنفيذ). + - تعود قيم `apiKey`/`baseUrl` الفارغة أو غير الموجودة في الوكيل إلى `models.providers` في الإعدادات. + - تستخدم القيم `contextWindow`/`maxTokens` للنموذج المطابق القيمة الأعلى بين الإعدادات الصريحة وقيم الفهرس الضمنية. + - تحتفظ `contextTokens` للنموذج المطابق بحد وقت التشغيل الصريح عندما يكون موجوداً؛ استخدمها لتقييد السياق الفعلي دون تغيير البيانات الوصفية الأصلية للنموذج. - استخدم `models.mode: "replace"` عندما تريد أن تعيد الإعدادات كتابة `models.json` بالكامل. - - يكون حفظ العلامات معتمدًا على المصدر: تُكتب العلامات من لقطة إعدادات المصدر النشطة (قبل الحل)، وليس من قيم الأسرار المحلولة وقت التشغيل. + - يكون حفظ العلامات مرجعياً بحسب المصدر: تُكتب العلامات من لقطة إعداد المصدر النشطة (قبل الحل)، لا من قيم الأسرار المحلولة وقت التشغيل. -### تفاصيل حقول الموفر +### تفاصيل حقول الموفّر -- `models.mode`: سلوك فهرس الموفر (`merge` أو `replace`). -- `models.providers`: خريطة موفّرين مخصصين مفاتيحها هي معرّفات الموفرين. -- `models.providers.*.api`: مهايئ الطلب (`openai-completions` أو `openai-responses` أو `anthropic-messages` أو `google-generative-ai`، إلخ). -- `models.providers.*.apiKey`: بيانات اعتماد الموفر (يُفضّل SecretRef/الاستبدال بمتغيرات البيئة). -- `models.providers.*.auth`: إستراتيجية المصادقة (`api-key` أو `token` أو `oauth` أو `aws-sdk`). -- `models.providers.*.injectNumCtxForOpenAICompat`: بالنسبة إلى Ollama + `openai-completions`، يحقن `options.num_ctx` في الطلبات (الافتراضي: `true`). -- `models.providers.*.authHeader`: يفرض نقل بيانات الاعتماد في ترويسة `Authorization` عند الحاجة. -- `models.providers.*.baseUrl`: عنوان URL الأساسي لواجهة API العليا. +- `models.mode`: سلوك فهرس الموفّرين (`merge` أو `replace`). +- `models.providers`: خريطة الموفّرين المخصصين مفاتيحها معرّفات الموفّر. +- `models.providers.*.api`: مهايئ الطلب (`openai-completions` أو `openai-responses` أو `anthropic-messages` أو `google-generative-ai` وما إلى ذلك). +- `models.providers.*.apiKey`: اعتماد الموفّر (يُفضّل SecretRef/الاستبدال عبر البيئة). +- `models.providers.*.auth`: استراتيجية المصادقة (`api-key` أو `token` أو `oauth` أو `aws-sdk`). +- `models.providers.*.injectNumCtxForOpenAICompat`: في Ollama + `openai-completions`، يحقن `options.num_ctx` داخل الطلبات (الافتراضي: `true`). +- `models.providers.*.authHeader`: يفرض نقل الاعتماد داخل ترويسة `Authorization` عند الحاجة. +- `models.providers.*.baseUrl`: عنوان URL الأساسي لواجهة API upstream. - `models.providers.*.headers`: ترويسات ثابتة إضافية لتوجيه proxy/المستأجر. -- `models.providers.*.request`: تجاوزات النقل لطلبات HTTP الخاصة بموفر النموذج. - - `request.headers`: ترويسات إضافية (تُدمج مع القيم الافتراضية للموفر). تقبل القيم SecretRef. - - `request.auth`: تجاوز إستراتيجية المصادقة. الأنماط: `"provider-default"` (استخدام المصادقة المضمّنة للموفر)، و`"authorization-bearer"` (مع `token`)، و`"header"` (مع `headerName` و`value` و`prefix` الاختياري). - - `request.proxy`: تجاوز HTTP proxy. الأنماط: `"env-proxy"` (استخدام متغيرات البيئة `HTTP_PROXY`/`HTTPS_PROXY`) و`"explicit-proxy"` (مع `url`). يقبل كلا النمطين كائنًا فرعيًا اختياريًا `tls`. - - `request.tls`: تجاوز TLS للاتصالات المباشرة. الحقول: `ca` و`cert` و`key` و`passphrase` (تقبل جميعها SecretRef) و`serverName` و`insecureSkipVerify`. - - `request.allowPrivateNetwork`: عندما تكون `true`، تسمح بـ HTTPS إلى `baseUrl` عندما يُحل DNS إلى نطاقات خاصة أو CGNAT أو نطاقات مشابهة، عبر حاجز جلب HTTP الخاص بالموفر (اشتراك تشغيلي اختياري لنقاط نهاية OpenAI-compatible ذاتية الاستضافة الموثوق بها). ويستخدم WebSocket نفس `request` للترويسات/TLS ولكن ليس لهذا الحاجز الخاص بـ SSRF في الجلب. الافتراضي `false`. -- `models.providers.*.models`: إدخالات فهرس نماذج موفر صريحة. -- `models.providers.*.models.*.contextWindow`: بيانات وصفية لنافذة سياق النموذج الأصلية. -- `models.providers.*.models.*.contextTokens`: حد اختياري لسياق وقت التشغيل. استخدمه عندما تريد ميزانية سياق فعلية أصغر من `contextWindow` الأصلية للنموذج. -- `models.providers.*.models.*.compat.supportsDeveloperRole`: تلميح توافق اختياري. بالنسبة إلى `api: "openai-completions"` مع `baseUrl` غير أصلي وغير فارغ (مضيف ليس `api.openai.com`)، يفرض OpenClaw هذه القيمة إلى `false` وقت التشغيل. أما `baseUrl` الفارغ/غير المعيّن فيُبقي سلوك OpenAI الافتراضي. -- `models.providers.*.models.*.compat.requiresStringContent`: تلميح توافق اختياري لنقاط نهاية chat المتوافقة مع OpenAI والتي تقبل السلاسل فقط. عندما تكون `true`، يقوم OpenClaw بتسطيح مصفوفات `messages[].content` النصية الخالصة إلى سلاسل عادية قبل إرسال الطلب. +- `models.providers.*.request`: تجاوزات النقل لطلبات HTTP الخاصة بموفّر النموذج. + - `request.headers`: ترويسات إضافية (تُدمج مع القيم الافتراضية للموفّر). تقبل القيم SecretRef. + - `request.auth`: تجاوز استراتيجية المصادقة. الأوضاع: `"provider-default"` (استخدام المصادقة المضمنة للموفّر)، و`"authorization-bearer"` (مع `token`)، و`"header"` (مع `headerName` و`value` و`prefix` الاختياري). + - `request.proxy`: تجاوز HTTP proxy. الأوضاع: `"env-proxy"` (استخدام متغيرات البيئة `HTTP_PROXY`/`HTTPS_PROXY`)، و`"explicit-proxy"` (مع `url`). يقبل كلا الوضعين كائناً فرعياً اختيارياً `tls`. + - `request.tls`: تجاوز TLS للاتصالات المباشرة. الحقول: `ca` و`cert` و`key` و`passphrase` (كلها تقبل SecretRef) و`serverName` و`insecureSkipVerify`. + - `request.allowPrivateNetwork`: عندما تكون `true`، تسمح باتصالات HTTPS إلى `baseUrl` عندما يُحل DNS إلى نطاقات خاصة أو CGNAT أو نطاقات مشابهة، عبر حارس جلب HTTP الخاص بالموفّر (تفعيل اختياري من المشغّل لنقاط نهاية OpenAI المتوافقة المستضافة ذاتياً والموثوقة). يستخدم WebSocket نفس `request` للترويسات/TLS لكن ليس لحارس SSRF الخاص بالجلب. الافتراضي `false`. +- `models.providers.*.models`: إدخالات فهرس نماذج الموفّر الصريحة. +- `models.providers.*.models.*.contextWindow`: بيانات تعريف نافذة السياق الأصلية للنموذج. +- `models.providers.*.models.*.contextTokens`: حد سياق اختياري لوقت التشغيل. استخدمه عندما تريد ميزانية سياق فعلية أصغر من `contextWindow` الأصلية للنموذج. +- `models.providers.*.models.*.compat.supportsDeveloperRole`: تلميح توافق اختياري. بالنسبة إلى `api: "openai-completions"` مع `baseUrl` غير أصلي وغير فارغ (مضيفه ليس `api.openai.com`)، يفرض OpenClaw هذه القيمة إلى `false` وقت التشغيل. ويبقي `baseUrl` الفارغ/المحذوف سلوك OpenAI الافتراضي. +- `models.providers.*.models.*.compat.requiresStringContent`: تلميح توافق اختياري لنقاط نهاية chat المتوافقة مع OpenAI والتي تقبل سلاسل فقط. عندما تكون `true`، يقوم OpenClaw بتسطيح مصفوفات `messages[].content` النصية الخالصة إلى سلاسل عادية قبل إرسال الطلب. - `plugins.entries.amazon-bedrock.config.discovery`: جذر إعدادات الاكتشاف التلقائي لـ Bedrock. - `plugins.entries.amazon-bedrock.config.discovery.enabled`: تشغيل/إيقاف الاكتشاف الضمني. - `plugins.entries.amazon-bedrock.config.discovery.region`: منطقة AWS الخاصة بالاكتشاف. -- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: عامل تصفية اختياري لمعرّف الموفر من أجل اكتشاف موجّه. +- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: مرشح معرّف موفّر اختياري للاكتشاف الموجّه. - `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: فاصل الاستطلاع لتحديث الاكتشاف. - `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: نافذة السياق الاحتياطية للنماذج المكتشفة. -- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: الحد الأقصى الاحتياطي لرموز الخرج للنماذج المكتشفة. +- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: الحد الأقصى الاحتياطي لرموز الإخراج للنماذج المكتشفة. -### أمثلة على الموفرين +### أمثلة على الموفّرين - -__OC_I18N_900066__ -استخدم `cerebras/zai-glm-4.7` مع Cerebras؛ واستخدم `zai/glm-4.7` مع Z.AI المباشر. + + +```json5 +{ + env: { CEREBRAS_API_KEY: "sk-..." }, + agents: { + defaults: { + model: { + primary: "cerebras/zai-glm-4.7", + fallbacks: ["cerebras/zai-glm-4.6"], + }, + models: { + "cerebras/zai-glm-4.7": { alias: "GLM 4.7 (Cerebras)" }, + "cerebras/zai-glm-4.6": { alias: "GLM 4.6 (Cerebras)" }, + }, + }, + }, + models: { + mode: "merge", + providers: { + cerebras: { + baseUrl: "https://api.cerebras.ai/v1", + apiKey: "${CEREBRAS_API_KEY}", + api: "openai-completions", + models: [ + { id: "zai-glm-4.7", name: "GLM 4.7 (Cerebras)" }, + { id: "zai-glm-4.6", name: "GLM 4.6 (Cerebras)" }, + ], + }, + }, + }, +} +``` + +استخدم `cerebras/zai-glm-4.7` مع Cerebras؛ و`zai/glm-4.7` مع Z.AI المباشر. -__OC_I18N_900067__ -عيّن `OPENCODE_API_KEY` (أو `OPENCODE_ZEN_API_KEY`). استخدم مراجع `opencode/...` لفهرس Zen أو مراجع `opencode-go/...` لفهرس Go. اختصار: `openclaw onboard --auth-choice opencode-zen` أو `openclaw onboard --auth-choice opencode-go`. + +```json5 +{ + agents: { + defaults: { + model: { primary: "opencode/claude-opus-4-6" }, + models: { "opencode/claude-opus-4-6": { alias: "Opus" } }, + }, + }, +} +``` + +اضبط `OPENCODE_API_KEY` (أو `OPENCODE_ZEN_API_KEY`). استخدم المراجع `opencode/...` لفهرس Zen أو المراجع `opencode-go/...` لفهرس Go. الاختصار: `openclaw onboard --auth-choice opencode-zen` أو `openclaw onboard --auth-choice opencode-go`. - -__OC_I18N_900068__ -عيّن `ZAI_API_KEY`. ويُقبل `z.ai/*` و`z-ai/*` كأسماء مستعارة. اختصار: `openclaw onboard --auth-choice zai-api-key`. + + +```json5 +{ + agents: { + defaults: { + model: { primary: "zai/glm-4.7" }, + models: { "zai/glm-4.7": {} }, + }, + }, +} +``` + +اضبط `ZAI_API_KEY`. ويُقبل `z.ai/*` و`z-ai/*` كأسماء مستعارة. الاختصار: `openclaw onboard --auth-choice zai-api-key`. - نقطة النهاية العامة: `https://api.z.ai/api/paas/v4` - نقطة نهاية البرمجة (الافتراضية): `https://api.z.ai/api/coding/paas/v4` -- بالنسبة إلى نقطة النهاية العامة، عرّف موفرًا مخصصًا مع تجاوز `baseUrl`. +- بالنسبة إلى نقطة النهاية العامة، عرّف موفّراً مخصصاً مع تجاوز `baseUrl`. - -__OC_I18N_900069__ -بالنسبة إلى نقطة النهاية الصينية: `baseUrl: "https://api.moonshot.cn/v1"` أو `openclaw onboard --auth-choice moonshot-api-key-cn`. + + +```json5 +{ + env: { MOONSHOT_API_KEY: "sk-..." }, + agents: { + defaults: { + model: { primary: "moonshot/kimi-k2.5" }, + models: { "moonshot/kimi-k2.5": { alias: "Kimi K2.5" } }, + }, + }, + models: { + mode: "merge", + providers: { + moonshot: { + baseUrl: "https://api.moonshot.ai/v1", + apiKey: "${MOONSHOT_API_KEY}", + api: "openai-completions", + models: [ + { + id: "kimi-k2.5", + name: "Kimi K2.5", + reasoning: false, + input: ["text", "image"], + cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, + contextWindow: 262144, + maxTokens: 262144, + }, + ], + }, + }, + }, +} +``` + +بالنسبة إلى نقطة نهاية الصين: `baseUrl: "https://api.moonshot.cn/v1"` أو `openclaw onboard --auth-choice moonshot-api-key-cn`. تعلن نقاط نهاية Moonshot الأصلية عن توافق استخدام البث على ناقل `openai-completions` المشترك، ويعتمد OpenClaw في ذلك على قدرات نقطة النهاية -وليس على معرّف الموفر المضمّن وحده. +وليس على معرّف الموفّر المضمن وحده. -__OC_I18N_900070__ -متوافق مع Anthropic، وموفر مضمّن. اختصار: `openclaw onboard --auth-choice kimi-code-api-key`. + +```json5 +{ + env: { KIMI_API_KEY: "sk-..." }, + agents: { + defaults: { + model: { primary: "kimi/kimi-code" }, + models: { "kimi/kimi-code": { alias: "Kimi Code" } }, + }, + }, +} +``` + +متوافق مع Anthropic، وموفّر مضمّن. الاختصار: `openclaw onboard --auth-choice kimi-code-api-key`. - -__OC_I18N_900071__ -يجب أن يحذف عنوان URL الأساسي `/v1` (إذ يضيفه عميل Anthropic). اختصار: `openclaw onboard --auth-choice synthetic-api-key`. + + +```json5 +{ + env: { SYNTHETIC_API_KEY: "sk-..." }, + agents: { + defaults: { + model: { primary: "synthetic/hf:MiniMaxAI/MiniMax-M2.5" }, + models: { "synthetic/hf:MiniMaxAI/MiniMax-M2.5": { alias: "MiniMax M2.5" } }, + }, + }, + models: { + mode: "merge", + providers: { + synthetic: { + baseUrl: "https://api.synthetic.new/anthropic", + apiKey: "${SYNTHETIC_API_KEY}", + api: "anthropic-messages", + models: [ + { + id: "hf:MiniMaxAI/MiniMax-M2.5", + name: "MiniMax M2.5", + reasoning: true, + input: ["text"], + cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, + contextWindow: 192000, + maxTokens: 65536, + }, + ], + }, + }, + }, +} +``` + +يجب ألا يتضمن `baseUrl` المسار `/v1` (لأن عميل Anthropic يضيفه). الاختصار: `openclaw onboard --auth-choice synthetic-api-key`. - -__OC_I18N_900072__ -عيّن `MINIMAX_API_KEY`. الاختصارات: + + +```json5 +{ + agents: { + defaults: { + model: { primary: "minimax/MiniMax-M2.7" }, + models: { + "minimax/MiniMax-M2.7": { alias: "Minimax" }, + }, + }, + }, + models: { + mode: "merge", + providers: { + minimax: { + baseUrl: "https://api.minimax.io/anthropic", + apiKey: "${MINIMAX_API_KEY}", + api: "anthropic-messages", + models: [ + { + id: "MiniMax-M2.7", + name: "MiniMax M2.7", + reasoning: true, + input: ["text", "image"], + cost: { input: 0.3, output: 1.2, cacheRead: 0.06, cacheWrite: 0.375 }, + contextWindow: 204800, + maxTokens: 131072, + }, + ], + }, + }, + }, +} +``` + +اضبط `MINIMAX_API_KEY`. الاختصارات: `openclaw onboard --auth-choice minimax-global-api` أو `openclaw onboard --auth-choice minimax-cn-api`. -يفترض فهرس النماذج قيمة M2.7 فقط. -وعلى مسار البث المتوافق مع Anthropic، يعطّل OpenClaw تفكير MiniMax -افتراضيًا ما لم تعيّن `thinking` بنفسك صراحة. ويقوم `/fast on` أو -`params.fastMode: true` بإعادة كتابة `MiniMax-M2.7` إلى +يفترض فهرس النماذج M2.7 فقط. +في مسار البث المتوافق مع Anthropic، يعطّل OpenClaw تفكير MiniMax +افتراضياً ما لم تضبط `thinking` بنفسك صراحةً. ويعيد `/fast on` أو +`params.fastMode: true` كتابة `MiniMax-M2.7` إلى `MiniMax-M2.7-highspeed`. -راجع [النماذج المحلية](/gateway/local-models). الخلاصة: شغّل نموذجًا محليًا كبيرًا عبر LM Studio Responses API على عتاد قوي؛ واحتفظ بالنماذج المستضافة مدمجة من أجل الاحتياط. +راجع [النماذج المحلية](/ar/gateway/local-models). باختصار: شغّل نموذجاً محلياً كبيراً عبر LM Studio Responses API على عتاد قوي؛ واحتفظ بالنماذج المستضافة مدمجة كخيار احتياطي. --- ## Skills -__OC_I18N_900073__ -- `allowBundled`: قائمة سماح اختيارية لـ Skills المضمّنة فقط (ولا تتأثر Skills المُدارة/الخاصة بمساحة العمل). -- `load.extraDirs`: جذور Skills مشتركة إضافية (أدنى أسبقية). -- `install.preferBrew`: عندما تكون `true`، تفضّل مثبّتات Homebrew عندما يكون `brew` - متاحًا قبل الرجوع إلى أنواع المثبّتات الأخرى. + +```json5 +{ + skills: { + allowBundled: ["gemini", "peekaboo"], + load: { + extraDirs: ["~/Projects/agent-scripts/skills"], + }, + install: { + preferBrew: true, + nodeManager: "npm", // npm | pnpm | yarn | bun + }, + entries: { + "image-lab": { + apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string + env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" }, + }, + peekaboo: { enabled: true }, + sag: { enabled: false }, + }, + }, +} +``` + +- `allowBundled`: قائمة سماح اختيارية لـ Skills المضمنة فقط (ولا تتأثر Skills المُدارة/الخاصة بمساحة العمل). +- `load.extraDirs`: جذور Skills مشتركة إضافية (الأدنى أولوية). +- `install.preferBrew`: عندما تكون true، يفضّل مثبّتات Homebrew عندما يكون `brew` + متاحاً قبل الرجوع إلى أنواع المثبّتات الأخرى. - `install.nodeManager`: تفضيل مثبّت Node لمواصفات `metadata.openclaw.install` (`npm` | `pnpm` | `yarn` | `bun`). - يؤدي `entries..enabled: false` إلى تعطيل Skill حتى لو كانت مضمّنة/مثبّتة. -- `entries..apiKey`: وسيلة مريحة لـ Skills التي تعلن متغير بيئة أساسيًا (سلسلة نصية صريحة أو كائن SecretRef). +- `entries..apiKey`: وسيلة ملائمة لـ Skills التي تعرّف متغير بيئة أساسياً (سلسلة نصية صريحة أو كائن SecretRef). --- ## Plugins -__OC_I18N_900074__ -- يُحمَّل من `~/.openclaw/extensions` و`/.openclaw/extensions` بالإضافة إلى `plugins.load.paths`. -- يقبل الاكتشاف OpenClaw plugins الأصلية بالإضافة إلى حزم Codex المتوافقة وحزم Claude، بما في ذلك حزم Claude ذات التخطيط الافتراضي من دون manifest. + +```json5 +{ + plugins: { + enabled: true, + allow: ["voice-call"], + deny: [], + load: { + paths: ["~/Projects/oss/voice-call-extension"], + }, + entries: { + "voice-call": { + enabled: true, + hooks: { + allowPromptInjection: false, + }, + config: { provider: "twilio" }, + }, + }, + }, +} +``` + +- يتم التحميل من `~/.openclaw/extensions` و`/.openclaw/extensions` بالإضافة إلى `plugins.load.paths`. +- يقبل الاكتشاف إضافات OpenClaw الأصلية بالإضافة إلى حزم Codex المتوافقة وحزم Claude، بما في ذلك حزم Claude ذات التخطيط الافتراضي من دون manifest. - **تتطلب تغييرات الإعدادات إعادة تشغيل البوابة.** -- `allow`: قائمة سماح اختيارية (لا تُحمّل إلا الـ plugins المدرجة). ويفوز `deny`. -- `plugins.entries..apiKey`: حقل ملاءمة لمفتاح API على مستوى plugin (عند دعمه من قبل plugin). -- `plugins.entries..env`: خريطة متغيرات بيئة خاصة بـ plugin. -- `plugins.entries..hooks.allowPromptInjection`: عندما تكون `false`، يمنع core `before_prompt_build` ويتجاهل الحقول المعدّلة للمطالبة من `before_agent_start` القديم، مع الحفاظ على `modelOverride` و`providerOverride` القديمين. وينطبق ذلك على plugin hooks الأصلية وأدلة hooks التي توفّرها الحزم المدعومة. -- `plugins.entries..subagent.allowModelOverride`: يثق صراحةً في هذا plugin لطلب تجاوزات `provider` و`model` لكل تشغيل في تشغيلات الوكلاء الفرعيين في الخلفية. -- `plugins.entries..subagent.allowedModels`: قائمة سماح اختيارية لأهداف `provider/model` القياسية من أجل تجاوزات الوكلاء الفرعيين الموثوق بها. استخدم `"*"` فقط عندما تريد عمدًا السماح بأي نموذج. -- `plugins.entries..config`: كائن إعدادات يعرّفه plugin (ويُتحقق منه عبر مخطط OpenClaw plugin الأصلي عند توفره). -- `plugins.entries.firecrawl.config.webFetch`: إعدادات موفر web-fetch في Firecrawl. - - `apiKey`: مفتاح API لـ Firecrawl (يقبل SecretRef). ويعود احتياطيًا إلى `plugins.entries.firecrawl.config.webSearch.apiKey`، أو `tools.web.fetch.firecrawl.apiKey` القديم، أو متغير البيئة `FIRECRAWL_API_KEY`. - - `baseUrl`: عنوان URL الأساسي لواجهة API الخاصة بـ Firecrawl (الافتراضي: `https://api.firecrawl.dev`). - - `onlyMainContent`: استخراج المحتوى الرئيسي للصفحات فقط (الافتراضي: `true`). - - `maxAgeMs`: الحد الأقصى لعمر ذاكرة التخزين المؤقت بالمللي ثانية (الافتراضي: `172800000` / يومان). - - `timeoutSeconds`: مهلة طلب الكشط بالثواني (الافتراضي: `60`). +- `allow`: قائمة سماح اختيارية (يتم تحميل الإضافات المدرجة فقط). ويفوز `deny`. +- `plugins.entries..apiKey`: حقل ملائم لمفتاح API على مستوى الـ plugin (عندما يدعمه الـ plugin). +- `plugins.entries..env`: خريطة متغيرات بيئة ضمن نطاق الـ plugin. +- `plugins.entries..hooks.allowPromptInjection`: عندما تكون `false`، يمنع core الخطاف `before_prompt_build` ويتجاهل الحقول القديمة المعدِّلة للـ prompt من `before_agent_start`، مع الحفاظ على `modelOverride` و`providerOverride` القديمين. وينطبق ذلك على خطافات الـ plugin الأصلية وعلى أدلة الخطافات المقدمة من الحزم المدعومة. +- `plugins.entries..subagent.allowModelOverride`: يثق صراحةً بهذا الـ plugin لطلب تجاوزات `provider` و`model` لكل تشغيل في التشغيلات الخلفية للوكلاء الفرعيين. +- `plugins.entries..subagent.allowedModels`: قائمة سماح اختيارية لأهداف `provider/model` القياسية لتجاوزات الوكلاء الفرعيين الموثوق بها. استخدم `"*"` فقط عندما تريد عمداً السماح بأي نموذج. +- `plugins.entries..config`: كائن إعداد يعرّفه الـ plugin (ويتم التحقق منه عبر مخطط OpenClaw plugin الأصلي عندما يكون متاحاً). +- `plugins.entries.firecrawl.config.webFetch`: إعدادات موفّر web-fetch الخاص بـ Firecrawl. + - `apiKey`: مفتاح API لـ Firecrawl (يقبل SecretRef). ويعود إلى `plugins.entries.firecrawl.config.webSearch.apiKey` أو `tools.web.fetch.firecrawl.apiKey` القديم أو متغير البيئة `FIRECRAWL_API_KEY`. + - `baseUrl`: عنوان URL الأساسي لـ API الخاص بـ Firecrawl (الافتراضي: `https://api.firecrawl.dev`). + - `onlyMainContent`: استخراج المحتوى الرئيسي فقط من الصفحات (الافتراضي: `true`). + - `maxAgeMs`: أقصى عمر للذاكرة المؤقتة بالمللي ثانية (الافتراضي: `172800000` / يومان). + - `timeoutSeconds`: مهلة طلب الاستخراج بالثواني (الافتراضي: `60`). - `plugins.entries.xai.config.xSearch`: إعدادات xAI X Search ‏(بحث الويب Grok). - - `enabled`: تفعيل موفر X Search. - - `model`: نموذج Grok المستخدم للبحث (مثل `"grok-4-1-fast"`). -- `plugins.entries.memory-core.config.dreaming`: إعدادات dreaming الخاصة بالذاكرة (تجريبية). راجع [Dreaming](/concepts/dreaming) للمراحل والعتبات. + - `enabled`: تفعيل موفّر X Search. + - `model`: نموذج Grok المراد استخدامه في البحث (مثلاً `"grok-4-1-fast"`). +- `plugins.entries.memory-core.config.dreaming`: إعدادات dreaming الخاصة بالذاكرة (تجريبية). راجع [Dreaming](/ar/concepts/dreaming) لمعرفة المراحل والعتبات. - `enabled`: المفتاح الرئيسي لـ dreaming (الافتراضي `false`). - - `frequency`: إيقاع cron لكل عملية dreaming كاملة (`"0 3 * * *"` افتراضيًا). - - سياسة المراحل والعتبات هي تفاصيل تنفيذية (وليست مفاتيح إعدادات موجّهة للمستخدم). -- توجد إعدادات الذاكرة الكاملة في [مرجع إعدادات الذاكرة](/reference/memory-config): + - `frequency`: تردد cron لكل عملية dreaming كاملة (`"0 3 * * *"` افتراضياً). + - تعد سياسة المراحل والعتبات تفاصيل تنفيذ داخلية (وليست مفاتيح إعدادات موجّهة للمستخدم). +- يوجد إعداد الذاكرة الكامل في [مرجع إعدادات الذاكرة](/ar/reference/memory-config): - `agents.defaults.memorySearch.*` - `memory.backend` - `memory.citations` - `memory.qmd.*` - `plugins.entries.memory-core.config.dreaming` -- يمكن أيضًا لحزم Claude plugin المفعّلة أن تسهم بقيم Pi افتراضية مضمّنة من `settings.json`؛ ويطبّق OpenClaw هذه القيم كإعدادات وكيل منقّاة، وليس كتصحيحات خام لإعدادات OpenClaw. -- `plugins.slots.memory`: اختر معرّف memory plugin النشط، أو `"none"` لتعطيل memory plugins. -- `plugins.slots.contextEngine`: اختر معرّف context engine plugin النشط؛ وتكون قيمته الافتراضية `"legacy"` ما لم تثبّت وتحدد محركًا آخر. -- `plugins.installs`: بيانات تعريف التثبيت التي يديرها CLI وتستخدمها `openclaw plugins update`. +- يمكن أيضاً لإضافات Claude bundle المفعلة أن تساهم بقيم Pi افتراضية مضمنة من `settings.json`؛ ويطبّقها OpenClaw كإعدادات وكيل منقحة، لا كتصحيحات إعدادات OpenClaw خام. +- `plugins.slots.memory`: اختر معرّف plugin الذاكرة النشط، أو `"none"` لتعطيل إضافات الذاكرة. +- `plugins.slots.contextEngine`: اختر معرّف plugin محرك السياق النشط؛ ويكون الافتراضي `"legacy"` ما لم تثبّت محركاً آخر وتحدده. +- `plugins.installs`: بيانات تعريف التثبيت التي تديرها CLI وتستخدمها `openclaw plugins update`. - تتضمن `source` و`spec` و`sourcePath` و`installPath` و`version` و`resolvedName` و`resolvedVersion` و`resolvedSpec` و`integrity` و`shasum` و`resolvedAt` و`installedAt`. - - تعامل مع `plugins.installs.*` بوصفها حالة مُدارة؛ ويفضّل استخدام أوامر CLI بدل التعديلات اليدوية. + - تعامل مع `plugins.installs.*` على أنها حالة مُدارة؛ وفضّل أوامر CLI على التعديلات اليدوية. -راجع [Plugins](/tools/plugin). +راجع [Plugins](/ar/tools/plugin). --- -## المتصفح -__OC_I18N_900075__ +## Browser + +```json5 +{ + browser: { + enabled: true, + evaluateEnabled: true, + defaultProfile: "user", + ssrfPolicy: { + // dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access + // allowPrivateNetwork: true, // legacy alias + // hostnameAllowlist: ["*.example.com", "example.com"], + // allowedHostnames: ["localhost"], + }, + profiles: { + openclaw: { cdpPort: 18800, color: "#FF4500" }, + work: { cdpPort: 18801, color: "#0066CC" }, + user: { driver: "existing-session", attachOnly: true, color: "#00AA00" }, + brave: { + driver: "existing-session", + attachOnly: true, + userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser", + color: "#FB542B", + }, + remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" }, + }, + color: "#FF4500", + // headless: false, + // noSandbox: false, + // extraArgs: [], + // executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser", + // attachOnly: false, + }, +} +``` + - يؤدي `evaluateEnabled: false` إلى تعطيل `act:evaluate` و`wait --fn`. -- يكون `ssrfPolicy.dangerouslyAllowPrivateNetwork` معطلًا عندما لا يتم تعيينه، لذلك تظل ملاحة المتصفح صارمة افتراضيًا. -- عيّن `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` فقط عندما تثق عمدًا في ملاحة المتصفح داخل الشبكات الخاصة. -- في الوضع الصارم، تخضع نقاط نهاية ملفات تعريف CDP البعيدة (`profiles.*.cdpUrl`) لحظر الشبكات الخاصة نفسه أثناء فحوصات الوصول/الاكتشاف. -- يظل `ssrfPolicy.allowPrivateNetwork` مدعومًا كاسم مستعار قديم. +- تكون `ssrfPolicy.dangerouslyAllowPrivateNetwork` معطلة عند عدم تعيينها، لذا تبقى ملاحة Browser صارمة افتراضياً. +- اضبط `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` فقط عندما تثق عمداً بملاحة Browser عبر الشبكة الخاصة. +- في الوضع الصارم، تخضع نقاط نهاية ملفات CDP البعيدة (`profiles.*.cdpUrl`) لنفس حظر الشبكة الخاصة أثناء فحوصات الوصول/الاكتشاف. +- تبقى `ssrfPolicy.allowPrivateNetwork` مدعومة كاسم مستعار قديم. - في الوضع الصارم، استخدم `ssrfPolicy.hostnameAllowlist` و`ssrfPolicy.allowedHostnames` للاستثناءات الصريحة. -- تكون الملفات الشخصية البعيدة في وضع attach-only (ويُعطّل البدء/الإيقاف/إعادة التعيين). +- تكون الملفات التعريفية البعيدة في وضع attach-only (ويُعطّل البدء/الإيقاف/إعادة التعيين). - يقبل `profiles.*.cdpUrl` القيم `http://` و`https://` و`ws://` و`wss://`. - استخدم HTTP(S) عندما تريد أن يكتشف OpenClaw ‏`/json/version`؛ واستخدم WS(S) - عندما يزوّدك الموفر بعنوان DevTools WebSocket URL مباشر. -- تكون ملفات تعريف `existing-session` خاصة بالمضيف فقط وتستخدم Chrome MCP بدلًا من CDP. -- يمكن لملفات تعريف `existing-session` تعيين `userDataDir` لاستهداف ملف تعريف - محدد لمتصفح قائم على Chromium مثل Brave أو Edge. -- تحتفظ ملفات تعريف `existing-session` بالقيود الحالية لمسار Chrome MCP: - إجراءات تعتمد على snapshot/ref بدل استهداف CSS selector، وخطافات رفع ملف واحد، - ومن دون تجاوزات لمهلة dialog، ومن دون `wait --load networkidle`، ومن دون - `responsebody` أو تصدير PDF أو اعتراض التنزيلات أو الإجراءات الدُفعية. -- تقوم ملفات تعريف `openclaw` المحلية المُدارة بتعيين `cdpPort` و`cdpUrl` تلقائيًا؛ لا - تعيّن `cdpUrl` صراحة إلا لـ CDP البعيد. -- ترتيب الاكتشاف التلقائي: المتصفح الافتراضي إذا كان قائمًا على Chromium ← Chrome ← Brave ← Edge ← Chromium ← Chrome Canary. -- خدمة التحكم: loopback فقط (ويُشتق المنفذ من `gateway.port`، والافتراضي `18791`). -- يضيف `extraArgs` أعلام تشغيل إضافية إلى بدء تشغيل Chromium المحلي (مثل - `--disable-gpu`، أو تحديد حجم النافذة، أو أعلام التصحيح). + استخدم HTTP(S) عندما تريد من OpenClaw اكتشاف `/json/version`؛ واستخدم WS(S) + عندما يوفّر لك مزوّدك عنوان WebSocket مباشر لـ DevTools. +- تكون ملفات `existing-session` التعريفية خاصة بالمضيف فقط وتستخدم Chrome MCP بدلاً من CDP. +- يمكن لملفات `existing-session` التعريفية تعيين `userDataDir` لاستهداف + ملف تعريف محدد لمتصفح قائم على Chromium مثل Brave أو Edge. +- تحتفظ ملفات `existing-session` التعريفية بحدود مسار Chrome MCP الحالية: + إجراءات تعتمد على snapshot/ref بدلاً من استهداف CSS selectors، وخطافات رفع + ملف واحد، وعدم وجود تجاوزات لمهلة dialogs، وعدم وجود `wait --load networkidle`، ولا + `responsebody` أو تصدير PDF أو اعتراض التنزيل أو الإجراءات الدفعية. +- تخصص ملفات `openclaw` المحلية المُدارة القيمتين `cdpPort` و`cdpUrl` تلقائياً؛ ولا + تضبط `cdpUrl` صراحةً إلا في حالة CDP البعيد. +- ترتيب الاكتشاف التلقائي: المتصفح الافتراضي إذا كان قائماً على Chromium ← Chrome ← Brave ← Edge ← Chromium ← Chrome Canary. +- خدمة التحكم: على loopback فقط (المنفذ مشتق من `gateway.port`، والافتراضي `18791`). +- يضيف `extraArgs` أعلام تشغيل إضافية إلى بدء Chromium المحلي (على سبيل المثال + `--disable-gpu` أو تحديد حجم النافذة أو أعلام التصحيح). --- ## UI -__OC_I18N_900076__ -- `seamColor`: لون التمييز لواجهة التطبيق الأصلية (لون فقاعة Talk Mode، إلخ). -- `assistant`: تجاوز هوية Control UI. ويعود احتياطيًا إلى هوية الوكيل النشط. + +```json5 +{ + ui: { + seamColor: "#FF4500", + assistant: { + name: "OpenClaw", + avatar: "CB", // emoji, short text, image URL, or data URI + }, + }, +} +``` + +- `seamColor`: لون التمييز لواجهة التطبيق الأصلية (صبغة فقاعة وضع Talk، وما إلى ذلك). +- `assistant`: تجاوز هوية Control UI. ويعود إلى هوية الوكيل النشط. --- ## البوابة -__OC_I18N_900077__ + +```json5 +{ + gateway: { + mode: "local", // local | remote + port: 18789, + bind: "loopback", + auth: { + mode: "token", // none | token | password | trusted-proxy + token: "your-token", + // password: "your-password", // or OPENCLAW_GATEWAY_PASSWORD + // trustedProxy: { userHeader: "x-forwarded-user" }, // for mode=trusted-proxy; see /gateway/trusted-proxy-auth + allowTailscale: true, + rateLimit: { + maxAttempts: 10, + windowMs: 60000, + lockoutMs: 300000, + exemptLoopback: true, + }, + }, + tailscale: { + mode: "off", // off | serve | funnel + resetOnExit: false, + }, + controlUi: { + enabled: true, + basePath: "/openclaw", + // root: "dist/control-ui", + // embedSandbox: "scripts", // strict | scripts | trusted + // allowExternalEmbedUrls: false, // dangerous: allow absolute external http(s) embed URLs + // allowedOrigins: ["https://control.example.com"], // required for non-loopback Control UI + // dangerouslyAllowHostHeaderOriginFallback: false, // dangerous Host-header origin fallback mode + // allowInsecureAuth: false, + // dangerouslyDisableDeviceAuth: false, + }, + remote: { + url: "ws://gateway.tailnet:18789", + transport: "ssh", // ssh | direct + token: "your-token", + // password: "your-password", + }, + trustedProxies: ["10.0.0.1"], + // Optional. Default false. + allowRealIpFallback: false, + tools: { + // Additional /tools/invoke HTTP denies + deny: ["browser"], + // Remove tools from the default HTTP deny list + allow: ["gateway"], + }, + push: { + apns: { + relay: { + baseUrl: "https://relay.example.com", + timeoutMs: 10000, + }, + }, + }, + }, +} +``` + -- `mode`: ‏`local` (تشغيل البوابة) أو `remote` (الاتصال ببوابة بعيدة). وترفض البوابة البدء ما لم يكن `local`. -- `port`: منفذ متعدد الإرسال واحد لكل من WS + HTTP. الأسبقية: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`. -- `bind`: ‏`auto` أو `loopback` (الافتراضي) أو `lan` (`0.0.0.0`) أو `tailnet` (عنوان Tailscale IP فقط) أو `custom`. +- `mode`: ‏`local` (تشغيل البوابة) أو `remote` (الاتصال ببوابة بعيدة). وترفض البوابة بدء التشغيل ما لم تكن القيمة `local`. +- `port`: منفذ واحد متعدد الإرسال لكل من WS + HTTP. الأسبقية: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`. +- `bind`: ‏`auto` أو `loopback` (الافتراضي) أو `lan` ‏(`0.0.0.0`) أو `tailnet` ‏(عنوان Tailscale IP فقط) أو `custom`. - **الأسماء المستعارة القديمة للربط**: استخدم قيم وضع الربط في `gateway.bind` (`auto` و`loopback` و`lan` و`tailnet` و`custom`)، وليس الأسماء المستعارة للمضيف (`0.0.0.0` و`127.0.0.1` و`localhost` و`::` و`::1`). -- **ملاحظة Docker**: يستمع الربط الافتراضي `loopback` على `127.0.0.1` داخل الحاوية. ومع شبكات Docker bridge ‏(`-p 18789:18789`) تصل الحركة على `eth0`، لذا تصبح البوابة غير قابلة للوصول. استخدم `--network host` أو عيّن `bind: "lan"` (أو `bind: "custom"` مع `customBindHost: "0.0.0.0"`) للاستماع على جميع الواجهات. -- **المصادقة**: مطلوبة افتراضيًا. وتتطلب عمليات الربط غير loopback مصادقة البوابة. وعمليًا يعني ذلك رمزًا مميزًا/كلمة مرور مشتركة أو reverse proxy واعيًا بالهوية مع `gateway.auth.mode: "trusted-proxy"`. ويولّد معالج onboarding رمزًا مميزًا افتراضيًا. -- إذا تم إعداد كل من `gateway.auth.token` و`gateway.auth.password` (بما في ذلك SecretRefs)، فعيّن `gateway.auth.mode` صراحةً إلى `token` أو `password`. وتفشل عمليات بدء التشغيل وتثبيت/إصلاح الخدمة عندما يكون الاثنان مُعدَّين ويكون الوضع غير معيّن. -- `gateway.auth.mode: "none"`: وضع صريح بلا مصادقة. استخدمه فقط مع إعدادات local loopback موثوق بها؛ ولا يُعرض هذا عمدًا في مطالبات onboarding. -- `gateway.auth.mode: "trusted-proxy"`: فوّض المصادقة إلى reverse proxy واعٍ بالهوية وثق في ترويسات الهوية القادمة من `gateway.trustedProxies` (راجع [Trusted Proxy Auth](/gateway/trusted-proxy-auth)). ويتوقع هذا الوضع مصدر proxy **غير loopback**؛ ولا تستوفي reverse proxies ذات loopback على المضيف نفسه متطلبات trusted-proxy auth. -- `gateway.auth.allowTailscale`: عندما تكون `true`، يمكن لترويسات هوية Tailscale Serve تلبية مصادقة Control UI/WebSocket (بعد التحقق عبر `tailscale whois`). أما نقاط نهاية HTTP API فلا تستخدم مصادقة ترويسات Tailscale هذه؛ بل تتبع وضع مصادقة HTTP العادي للبوابة. ويفترض هذا التدفق بلا رمز مميز أن مضيف البوابة موثوق. وتكون القيمة الافتراضية `true` عندما يكون `tailscale.mode = "serve"`. -- `gateway.auth.rateLimit`: محدِّد اختياري لفشل المصادقة. ويُطبَّق لكل عنوان IP للعميل ولكل نطاق مصادقة (يُتتبَّع السر المشترك ورمز الجهاز بشكل مستقل). وتُرجع المحاولات المحظورة `429` + `Retry-After`. - - على مسار Control UI غير المتزامن عبر Tailscale Serve، تتم مَسلسلة المحاولات الفاشلة لنفس `{scope, clientIp}` قبل كتابة الفشل. لذا يمكن للمحاولات المتزامنة السيئة من العميل نفسه أن تفعّل المحدِّد في الطلب الثاني بدلًا من أن يمر الاثنان كتعارضات عادية. - - تكون القيمة الافتراضية لـ `gateway.auth.rateLimit.exemptLoopback` هي `true`؛ عيّنها إلى `false` عندما تريد عمدًا إخضاع حركة localhost لتحديد المعدل أيضًا (في إعدادات الاختبار أو عمليات نشر proxy الصارمة). -- يتم دائمًا تقييد محاولات مصادقة WS ذات أصل المتصفح مع تعطيل إعفاء loopback (كإجراء دفاعي إضافي ضد هجمات brute force على localhost من المتصفح). -- على loopback، تُعزل عمليات القفل ذات أصل المتصفح هذه لكل قيمة `Origin` - مُطبَّعة، لذلك لا تؤدي الإخفاقات المتكررة من أصل localhost واحد تلقائيًا - إلى قفل أصل مختلف. -- `tailscale.mode`: ‏`serve` (tailnet فقط، مع ربط loopback) أو `funnel` (عام، ويتطلب مصادقة). -- `controlUi.allowedOrigins`: قائمة سماح صريحة لأصول المتصفح لاتصالات Gateway WebSocket. وهي مطلوبة عندما يُتوقع عملاء متصفح من أصول غير loopback. -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: وضع خطير يفعّل الرجوع الاحتياطي إلى أصل Host-header في عمليات النشر التي تعتمد عمدًا على سياسة أصل Host-header. -- `remote.transport`: ‏`ssh` (الافتراضي) أو `direct` (ws/wss). وبالنسبة إلى `direct`، يجب أن تكون `remote.url` هي `ws://` أو `wss://`. -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: تجاوز كسر الزجاج من جهة العميل يسمح باستخدام `ws://` غير المشفر مع عناوين IP موثوقة داخل الشبكات الخاصة؛ بينما يبقى الافتراضي مقصورًا على loopback فقط للنص الصريح. -- `gateway.remote.token` / `.password`: حقول بيانات اعتماد العميل البعيد. وهي لا تهيّئ مصادقة البوابة بحد ذاتها. -- `gateway.push.apns.relay.baseUrl`: عنوان HTTPS الأساسي للـ APNs relay الخارجي الذي تستخدمه إصدارات iOS الرسمية/TestFlight بعد أن تنشر تسجيلات مدعومة بالـ relay إلى البوابة. ويجب أن يطابق هذا العنوان عنوان relay المضمّن أثناء بناء إصدار iOS. -- `gateway.push.apns.relay.timeoutMs`: مهلة الإرسال من البوابة إلى relay بالمللي ثانية. الافتراضي `10000`. -- تُفوّض التسجيلات المدعومة بالـ relay إلى هوية بوابة محددة. ويجلب تطبيق iOS المقترن `gateway.identity.get`، ويضمّن تلك الهوية في تسجيل relay، ويمرّر منحة إرسال خاصة بالتسجيل إلى البوابة. ولا يمكن لبوابة أخرى إعادة استخدام هذا التسجيل المخزَّن. -- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: تجاوزات بيئة مؤقتة لإعداد relay أعلاه. -- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: منفذ هروب مخصص للتطوير فقط لعناوين relay على loopback عبر HTTP. وينبغي أن تبقى عناوين relay الإنتاجية على HTTPS. -- `gateway.channelHealthCheckMinutes`: فاصل مراقبة صحة القنوات بالدقائق. عيّنه إلى `0` لتعطيل إعادة التشغيل عبر مراقب الصحة عالميًا. الافتراضي: `5`. -- `gateway.channelStaleEventThresholdMinutes`: عتبة المقبس القديم بالدقائق. اجعل هذه القيمة أكبر من أو مساوية لـ `gateway.channelHealthCheckMinutes`. الافتراضي: `30`. -- `gateway.channelMaxRestartsPerHour`: الحد الأقصى لإعادات التشغيل عبر مراقب الصحة لكل قناة/حساب ضمن ساعة متحركة. الافتراضي: `10`. -- `channels..healthMonitor.enabled`: تعطيل اختياري لكل قناة لإعادات تشغيل مراقب الصحة مع إبقاء المراقب العام مفعّلًا. -- `channels..accounts..healthMonitor.enabled`: تجاوز لكل حساب في القنوات متعددة الحسابات. وعند تعيينه، تكون له الأولوية على التجاوز على مستوى القناة. -- يمكن لمسارات استدعاء البوابة المحلية استخدام `gateway.remote.*` كخيار احتياطي فقط عندما تكون `gateway.auth.*` غير معيّنة. -- إذا تم إعداد `gateway.auth.token` / `gateway.auth.password` صراحة عبر SecretRef وكان غير محلول، يفشل الحل بشكل مغلق (من دون إخفاء عبر احتياطي remote). -- `trustedProxies`: عناوين IP الخاصة بالـ reverse proxy التي تنهي TLS أو تحقن ترويسات العميل المُعاد توجيهها. أدرج فقط الـ proxies التي تتحكم بها. وتظل إدخالات loopback صالحة لإعدادات proxy على المضيف نفسه/كشف المحلي (مثل Tailscale Serve أو reverse proxy محلي)، لكنها **لا** تجعل طلبات loopback مؤهلة لـ `gateway.auth.mode: "trusted-proxy"`. -- `allowRealIpFallback`: عندما تكون `true`، تقبل البوابة `X-Real-IP` إذا كان `X-Forwarded-For` مفقودًا. الافتراضي `false` لسلوك الفشل المغلق. -- `gateway.tools.deny`: أسماء أدوات إضافية محظورة لطلبات HTTP ‏`POST /tools/invoke` (توسّع قائمة المنع الافتراضية). -- `gateway.tools.allow`: إزالة أسماء أدوات من قائمة المنع الافتراضية لـ HTTP. +- **ملاحظة Docker**: يستمع الربط الافتراضي `loopback` على `127.0.0.1` داخل الحاوية. ومع Docker bridge networking ‏(`-p 18789:18789`) تصل الحركة إلى `eth0`، لذلك تصبح البوابة غير قابلة للوصول. استخدم `--network host`، أو اضبط `bind: "lan"` (أو `bind: "custom"` مع `customBindHost: "0.0.0.0"`) للاستماع على جميع الواجهات. +- **المصادقة**: مطلوبة افتراضياً. وتتطلب عمليات الربط غير loopback مصادقة البوابة. وعملياً يعني ذلك رمزاً مميزاً/كلمة مرور مشتركة أو reverse proxy واعياً بالهوية مع `gateway.auth.mode: "trusted-proxy"`. ويولّد معالج الإعداد رمزاً مميزاً افتراضياً. +- إذا تم إعداد كل من `gateway.auth.token` و`gateway.auth.password` (بما في ذلك SecretRefs)، فاضبط `gateway.auth.mode` صراحةً على `token` أو `password`. وتفشل عمليات بدء التشغيل وتثبيت/إصلاح الخدمة عندما يكون كلاهما مُعداً ويكون الوضع غير مضبوط. +- `gateway.auth.mode: "none"`: وضع صريح بلا مصادقة. استخدمه فقط في إعدادات local loopback الموثوقة؛ ولا يُعرض هذا عمداً في مطالبات الإعداد. +- `gateway.auth.mode: "trusted-proxy"`: فوّض المصادقة إلى reverse proxy واعٍ بالهوية وثق في ترويسات الهوية القادمة من `gateway.trustedProxies` (راجع [Trusted Proxy Auth](/ar/gateway/trusted-proxy-auth)). يتوقع هذا الوضع **مصدراً وكيلاً غير loopback**؛ ولا تستوفي reverse proxies المحلية على المضيف نفسه متطلبات مصادقة trusted-proxy. +- `gateway.auth.allowTailscale`: عندما تكون `true`، يمكن لترويسات هوية Tailscale Serve تلبية مصادقة Control UI/WebSocket (بعد التحقق عبر `tailscale whois`). ولا تستخدم نقاط نهاية HTTP API مصادقة ترويسات Tailscale هذه؛ بل تتبع وضع مصادقة HTTP العادي للبوابة. ويفترض هذا التدفق من دون رمز مميز أن مضيف البوابة موثوق. وتكون القيمة الافتراضية `true` عندما تكون `tailscale.mode = "serve"`. +- `gateway.auth.rateLimit`: محدِّد اختياري لمحاولات المصادقة الفاشلة. ويُطبَّق لكل عنوان IP عميل ولكل نطاق مصادقة (يتم تتبع السر المشترك ورمز الجهاز كلٌ على حدة). وتُرجع المحاولات المحظورة `429` + `Retry-After`. + - في مسار Control UI غير المتزامن لـ Tailscale Serve، تتم سلسلة المحاولات الفاشلة لنفس `{scope, clientIp}` قبل كتابة الفشل. لذلك قد تؤدي المحاولات السيئة المتزامنة من العميل نفسه إلى تشغيل المحدِّد عند الطلب الثاني بدلاً من أن يمر الطلبان معاً كحالات عدم تطابق عادية. + - تكون القيمة الافتراضية لـ `gateway.auth.rateLimit.exemptLoopback` هي `true`؛ اضبطها على `false` عندما تريد عمداً أن تخضع حركة localhost أيضاً للتحديد بالمعدل (لإعدادات الاختبار أو عمليات نشر proxy الصارمة). +- يتم دائماً تقييد محاولات مصادقة WS ذات الأصل المتصفحي مع تعطيل إعفاء loopback (دفاعاً إضافياً ضد محاولات التخمين العنيف لـ localhost من المتصفح). +- على loopback، تكون عمليات القفل هذه ذات الأصل المتصفحي معزولة حسب + قيمة `Origin` المطَبَّعة، بحيث لا تؤدي الإخفاقات المتكررة من أصل localhost واحد + تلقائياً إلى قفل أصل مختلف. +- `tailscale.mode`: ‏`serve` (tailnet فقط، مع bind على loopback) أو `funnel` (عام، ويتطلب المصادقة). +- `controlUi.allowedOrigins`: قائمة سماح صريحة لأصول المتصفح لاتصالات WebSocket الخاصة بالبوابة. وهي مطلوبة عندما يُتوقع وجود عملاء متصفح من أصول غير loopback. +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: وضع خطير يفعّل الرجوع إلى أصل Host-header لعمليات النشر التي تعتمد عمداً على سياسة أصل Host-header. +- `remote.transport`: ‏`ssh` (الافتراضي) أو `direct` ‏(ws/wss). وبالنسبة إلى `direct`، يجب أن يكون `remote.url` بصيغة `ws://` أو `wss://`. +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: تجاوز طارئ من جهة العميل يسمح باستخدام `ws://` النصي مع عناوين IP للشبكات الخاصة الموثوقة؛ ويظل الافتراضي مقصوراً على loopback فقط للاتصالات النصية. +- الحقلان `gateway.remote.token` / `.password` هما حقلا اعتماد للعميل البعيد. وهما لا يهيئان مصادقة البوابة بحد ذاتهما. +- `gateway.push.apns.relay.baseUrl`: عنوان HTTPS الأساسي لمرحل APNs الخارجي الذي تستخدمه إصدارات iOS الرسمية/TestFlight بعد أن تنشر تسجيلات مدعومة بالمرحل إلى البوابة. ويجب أن يطابق هذا العنوان عنوان المرحل المضمن في إصدار iOS. +- `gateway.push.apns.relay.timeoutMs`: مهلة الإرسال من البوابة إلى المرحل بالمللي ثانية. القيمة الافتراضية هي `10000`. +- تُفوَّض التسجيلات المدعومة بالمرحل إلى هوية محددة للبوابة. حيث يجلب تطبيق iOS المقترن القيمة `gateway.identity.get`، ويضمّن تلك الهوية في تسجيل المرحل، ويمرر منحة إرسال ضمن نطاق التسجيل إلى البوابة. ولا يمكن لبوابة أخرى إعادة استخدام هذا التسجيل المخزن. +- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: تجاوزات بيئية مؤقتة لإعداد المرحل أعلاه. +- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: منفذ طوارئ مخصص للتطوير لعناوين URL الخاصة بمرحل HTTP على loopback. ويجب أن تبقى عناوين URL الخاصة بالمرحل الإنتاجي على HTTPS. +- `gateway.channelHealthCheckMinutes`: فاصل مراقبة صحة القنوات بالدقائق. اضبطه على `0` لتعطيل إعادة تشغيل مراقب الصحة على مستوى العالم. الافتراضي: `5`. +- `gateway.channelStaleEventThresholdMinutes`: عتبة المقبس القديم بالدقائق. اجعلها أكبر من أو مساوية لـ `gateway.channelHealthCheckMinutes`. الافتراضي: `30`. +- `gateway.channelMaxRestartsPerHour`: الحد الأقصى لإعادات تشغيل مراقب الصحة لكل قناة/حساب خلال ساعة متحركة. الافتراضي: `10`. +- `channels..healthMonitor.enabled`: تعطيل اختياري لكل قناة لإعادات تشغيل مراقب الصحة مع إبقاء المراقب العام مفعلاً. +- `channels..accounts..healthMonitor.enabled`: تجاوز لكل حساب للقنوات متعددة الحسابات. وعند تعيينه، تكون له أولوية على تجاوز مستوى القناة. +- يمكن لمسارات استدعاء البوابة المحلية استخدام `gateway.remote.*` كخيار احتياطي فقط عندما لا تكون `gateway.auth.*` معينة. +- إذا كانت `gateway.auth.token` / `gateway.auth.password` مُعدّة صراحةً عبر SecretRef وكانت غير محلولة، فإن الحل يفشل بإغلاق آمن (من دون إخفاء عبر رجوع احتياطي بعيد). +- `trustedProxies`: عناوين IP الخاصة بالـ reverse proxy التي تنهي TLS أو تحقن ترويسات العميل المُمرَّر. أدرج فقط الوكلاء الذين تتحكم بهم. وتظل إدخالات loopback صالحة لإعدادات اكتشاف proxy المحلي/المضيف نفسه (مثل Tailscale Serve أو reverse proxy محلي)، لكنها **لا** تجعل طلبات loopback مؤهلة لـ `gateway.auth.mode: "trusted-proxy"`. +- `allowRealIpFallback`: عندما تكون `true`، تقبل البوابة `X-Real-IP` إذا كان `X-Forwarded-For` مفقوداً. الافتراضي `false` لسلوك إغلاق آمن. +- `gateway.tools.deny`: أسماء أدوات إضافية محظورة لاستدعاء HTTP `POST /tools/invoke` (تمتد فوق قائمة الحظر الافتراضية). +- `gateway.tools.allow`: إزالة أسماء أدوات من قائمة الحظر الافتراضية لـ HTTP. ### نقاط النهاية المتوافقة مع OpenAI -- Chat Completions: معطّلة افتراضيًا. فعّلها باستخدام `gateway.http.endpoints.chatCompletions.enabled: true`. +- Chat Completions: معطلة افتراضياً. فعّلها عبر `gateway.http.endpoints.chatCompletions.enabled: true`. - Responses API: ‏`gateway.http.endpoints.responses.enabled`. -- تقوية مدخلات URL في Responses: +- تقوية URL-input الخاصة بـ Responses: - `gateway.http.endpoints.responses.maxUrlParts` - `gateway.http.endpoints.responses.files.urlAllowlist` - `gateway.http.endpoints.responses.images.urlAllowlist` تُعامل قوائم السماح الفارغة على أنها غير معيّنة؛ استخدم `gateway.http.endpoints.responses.files.allowUrl=false` و/أو `gateway.http.endpoints.responses.images.allowUrl=false` لتعطيل جلب URL. - ترويسة اختيارية لتقوية الاستجابة: - - `gateway.http.securityHeaders.strictTransportSecurity` (عيّنها فقط لأصول HTTPS التي تتحكم بها؛ راجع [Trusted Proxy Auth](/gateway/trusted-proxy-auth#tls-termination-and-hsts)) + - `gateway.http.securityHeaders.strictTransportSecurity` (اضبطها فقط لأصول HTTPS التي تتحكم بها؛ راجع [Trusted Proxy Auth](/ar/gateway/trusted-proxy-auth#tls-termination-and-hsts)) ### العزل متعدد المثيلات شغّل عدة بوابات على مضيف واحد مع منافذ وأدلة حالة فريدة: -__OC_I18N_900078__ -أعلام ملاءمة: `--dev` (يستخدم `~/.openclaw-dev` + المنفذ `19001`)، و`--profile ` (يستخدم `~/.openclaw-`). -راجع [بوابات متعددة](/gateway/multiple-gateways). +```bash +OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \ +OPENCLAW_STATE_DIR=~/.openclaw-a \ +openclaw gateway --port 19001 +``` + +أعلام مريحة: `--dev` (يستخدم `~/.openclaw-dev` + المنفذ `19001`) و`--profile ` (يستخدم `~/.openclaw-`). + +راجع [Multiple Gateways](/ar/gateway/multiple-gateways). ### `gateway.tls` -__OC_I18N_900079__ + +```json5 +{ + gateway: { + tls: { + enabled: false, + autoGenerate: false, + certPath: "/etc/openclaw/tls/server.crt", + keyPath: "/etc/openclaw/tls/server.key", + caPath: "/etc/openclaw/tls/ca-bundle.crt", + }, + }, +} +``` + - `enabled`: يفعّل إنهاء TLS عند مستمع البوابة (HTTPS/WSS) (الافتراضي: `false`). -- `autoGenerate`: يُولّد تلقائيًا زوج cert/key محليًا موقّعًا ذاتيًا عندما لا تكون الملفات الصريحة مُعدّة؛ للاستخدام المحلي/التطوير فقط. +- `autoGenerate`: يولّد تلقائياً زوج شهادة/مفتاح محلياً موقّعاً ذاتياً عندما لا تكون الملفات الصريحة مُعدّة؛ للاستخدام المحلي/التطويري فقط. - `certPath`: مسار نظام الملفات إلى ملف شهادة TLS. -- `keyPath`: مسار نظام الملفات إلى ملف المفتاح الخاص لـ TLS؛ ويجب إبقاء أذوناته مقيّدة. -- `caPath`: مسار اختياري لحزمة CA من أجل التحقق من العميل أو سلاسل الثقة المخصصة. +- `keyPath`: مسار نظام الملفات إلى ملف المفتاح الخاص لـ TLS؛ ويجب تقييد أذوناته. +- `caPath`: مسار اختياري إلى حزمة CA للتحقق من العميل أو سلاسل الثقة المخصصة. ### `gateway.reload` -__OC_I18N_900080__ + +```json5 +{ + gateway: { + reload: { + mode: "hybrid", // off | restart | hot | hybrid + debounceMs: 500, + deferralTimeoutMs: 300000, + }, + }, +} +``` + - `mode`: يتحكم في كيفية تطبيق تعديلات الإعدادات وقت التشغيل. - - `"off"`: تجاهل التعديلات الحية؛ وتتطلب التغييرات إعادة تشغيل صريحة. - - `"restart"`: أعد تشغيل عملية البوابة دائمًا عند تغيير الإعدادات. + - `"off"`: تجاهل التعديلات المباشرة؛ وتتطلب التغييرات إعادة تشغيل صريحة. + - `"restart"`: أعد تشغيل عملية البوابة دائماً عند تغير الإعداد. - `"hot"`: طبّق التغييرات داخل العملية من دون إعادة تشغيل. - - `"hybrid"` (الافتراضي): جرّب أولًا إعادة التحميل الساخنة؛ وارجع إلى إعادة التشغيل إذا لزم الأمر. -- `debounceMs`: نافذة إزالة ارتداد بالمللي ثانية قبل تطبيق تغييرات الإعدادات (عدد صحيح غير سالب). + - `"hybrid"` (الافتراضي): حاول أولاً إعادة التحميل الحي؛ ثم ارجع إلى إعادة التشغيل إذا لزم الأمر. +- `debounceMs`: نافذة إزالة الارتداد بالمللي ثانية قبل تطبيق تغييرات الإعداد (عدد صحيح غير سالب). - `deferralTimeoutMs`: الحد الأقصى للوقت بالمللي ثانية لانتظار العمليات الجارية قبل فرض إعادة التشغيل (الافتراضي: `300000` = 5 دقائق). --- ## Hooks -__OC_I18N_900081__ + +```json5 +{ + hooks: { + enabled: true, + token: "shared-secret", + path: "/hooks", + maxBodyBytes: 262144, + defaultSessionKey: "hook:ingress", + allowRequestSessionKey: false, + allowedSessionKeyPrefixes: ["hook:"], + allowedAgentIds: ["hooks", "main"], + presets: ["gmail"], + transformsDir: "~/.openclaw/hooks/transforms", + mappings: [ + { + match: { path: "gmail" }, + action: "agent", + agentId: "hooks", + wakeMode: "now", + name: "Gmail", + sessionKey: "hook:gmail:{{messages[0].id}}", + messageTemplate: "From: {{messages[0].from}}\nSubject: {{messages[0].subject}}\n{{messages[0].snippet}}", + deliver: true, + channel: "last", + model: "openai/gpt-5.4-mini", + }, + ], + }, +} +``` + المصادقة: `Authorization: Bearer ` أو `x-openclaw-token: `. -وتُرفض رموز hooks المميزة في query-string. +تُرفض رموز hook المميزة في سلسلة الاستعلام. ملاحظات التحقق والأمان: - يتطلب `hooks.enabled=true` قيمة غير فارغة لـ `hooks.token`. - يجب أن تكون `hooks.token` **مختلفة** عن `gateway.auth.token`؛ ويُرفض إعادة استخدام رمز البوابة. -- لا يمكن أن تكون `hooks.path` هي `/`؛ استخدم مسارًا فرعيًا مخصصًا مثل `/hooks`. -- إذا كانت `hooks.allowRequestSessionKey=true`، فقيّد `hooks.allowedSessionKeyPrefixes` (مثل `["hook:"]`). +- لا يمكن أن يكون `hooks.path` هو `/`؛ استخدم مساراً فرعياً مخصصاً مثل `/hooks`. +- إذا كانت `hooks.allowRequestSessionKey=true`، فقيد `hooks.allowedSessionKeyPrefixes` (على سبيل المثال `["hook:"]`). **نقاط النهاية:** - `POST /hooks/wake` ← ‏`{ text, mode?: "now"|"next-heartbeat" }` - `POST /hooks/agent` ← ‏`{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }` - - لا يُقبل `sessionKey` من حمولة الطلب إلا عندما تكون `hooks.allowRequestSessionKey=true` (الافتراضي: `false`). -- `POST /hooks/` ← تُحل عبر `hooks.mappings` + - لا تُقبل `sessionKey` من حمولة الطلب إلا عندما تكون `hooks.allowRequestSessionKey=true` (الافتراضي: `false`). +- `POST /hooks/` ← يتم حلها عبر `hooks.mappings` - + -- يطابق `match.path` المسار الفرعي بعد `/hooks` (مثل `/hooks/gmail` ← `gmail`). -- يطابق `match.source` حقلًا في الحمولة للمسارات العامة. +- يطابق `match.path` المسار الفرعي بعد `/hooks` (مثلاً `/hooks/gmail` ← `gmail`). +- يطابق `match.source` حقلاً من الحمولة للمسارات العامة. - تقرأ القوالب مثل `{{messages[0].subject}}` من الحمولة. -- يمكن أن يشير `transform` إلى وحدة JS/TS تُرجع إجراء hook. - - يجب أن يكون `transform.module` مسارًا نسبيًا ويبقى ضمن `hooks.transformsDir` (وتُرفض المسارات المطلقة واجتياز المسارات). -- يوجّه `agentId` إلى وكيل محدد؛ وتعود المعرّفات غير المعروفة احتياطيًا إلى الوكيل الافتراضي. -- `allowedAgentIds`: يقيّد التوجيه الصريح (`*` أو المحذوف = السماح للجميع، و`[]` = منع الجميع). +- يمكن أن يشير `transform` إلى وحدة JS/TS تعيد إجراء hook. + - يجب أن يكون `transform.module` مساراً نسبياً وأن يبقى ضمن `hooks.transformsDir` (تُرفض المسارات المطلقة وعمليات traversal). +- يوجّه `agentId` إلى وكيل محدد؛ وتعود المعرّفات غير المعروفة إلى الوكيل الافتراضي. +- `allowedAgentIds`: يقيّد التوجيه الصريح (`*` أو الحذف = السماح للجميع، `[]` = منع الجميع). - `defaultSessionKey`: مفتاح جلسة ثابت اختياري لتشغيلات وكيل hook من دون `sessionKey` صريح. -- `allowRequestSessionKey`: السماح لمستدعِي `/hooks/agent` بتعيين `sessionKey` (الافتراضي: `false`). -- `allowedSessionKeyPrefixes`: قائمة سماح اختيارية للبادئات لقيم `sessionKey` الصريحة (الطلب + الربط)، مثل `["hook:"]`. +- `allowRequestSessionKey`: السماح لمستدعي `/hooks/agent` بتعيين `sessionKey` (الافتراضي: `false`). +- `allowedSessionKeyPrefixes`: قائمة سماح اختيارية للبادئات لقيم `sessionKey` الصريحة (الطلب + التعيين)، مثل `["hook:"]`. - يؤدي `deliver: true` إلى إرسال الرد النهائي إلى قناة؛ وتكون القيمة الافتراضية لـ `channel` هي `last`. -- يتجاوز `model` قيمة LLM لهذا التشغيل الخاص بـ hook (ويجب أن يكون مسموحًا به إذا كان فهرس النماذج معينًا). +- يتجاوز `model` قيمة LLM لتشغيل هذا hook (ويجب أن يكون مسموحاً به إذا كان فهرس النماذج مضبوطاً). ### تكامل Gmail -__OC_I18N_900082__ -- تبدأ البوابة تلقائيًا `gog gmail watch serve` عند الإقلاع عندما يكون معدًا. عيّن `OPENCLAW_SKIP_GMAIL_WATCHER=1` لتعطيله. -- لا تشغّل `gog gmail watch serve` منفصلًا إلى جانب البوابة. + +```json5 +{ + hooks: { + gmail: { + account: "openclaw@gmail.com", + topic: "projects//topics/gog-gmail-watch", + subscription: "gog-gmail-watch-push", + pushToken: "shared-push-token", + hookUrl: "http://127.0.0.1:18789/hooks/gmail", + includeBody: true, + maxBytes: 20000, + renewEveryMinutes: 720, + serve: { bind: "127.0.0.1", port: 8788, path: "/" }, + tailscale: { mode: "funnel", path: "/gmail-pubsub" }, + model: "openrouter/meta-llama/llama-3.3-70b-instruct:free", + thinking: "off", + }, + }, +} +``` + +- تبدأ البوابة تلقائياً `gog gmail watch serve` عند الإقلاع عندما يكون مضبطاً. اضبط `OPENCLAW_SKIP_GMAIL_WATCHER=1` لتعطيله. +- لا تشغّل `gog gmail watch serve` منفصلاً إلى جانب البوابة. --- -## Canvas host -__OC_I18N_900083__ -- يقدّم HTML/CSS/JS وA2UI القابلة للتحرير بواسطة الوكيل عبر HTTP تحت منفذ البوابة: +## مضيف Canvas + +```json5 +{ + canvasHost: { + root: "~/.openclaw/workspace/canvas", + liveReload: true, + // enabled: false, // or OPENCLAW_SKIP_CANVAS_HOST=1 + }, +} +``` + +- يقدّم HTML/CSS/JS وA2UI القابلة للتحرير من الوكيل عبر HTTP تحت منفذ البوابة: - `http://:/__openclaw__/canvas/` - `http://:/__openclaw__/a2ui/` - محلي فقط: أبقِ `gateway.bind: "loopback"` (الافتراضي). -- مع الربط غير loopback: تتطلب مسارات canvas مصادقة البوابة (token/password/trusted-proxy)، مثل بقية أسطح HTTP الخاصة بالبوابة. -- لا ترسل Node WebViews عادةً ترويسات مصادقة؛ وبعد إقران node واتصاله، تعلن البوابة عناوين capability URLs خاصة بـ node للوصول إلى canvas/A2UI. -- ترتبط capability URLs بجلسة WS الخاصة بـ node النشطة وتنتهي صلاحيتها سريعًا. ولا يُستخدم احتياطي قائم على IP. -- يحقن عميل live-reload في HTML المُقدَّم. -- ينشئ تلقائيًا `index.html` ابتدائيًا عندما يكون المجلد فارغًا. -- يقدّم أيضًا A2UI عند `/__openclaw__/a2ui/`. +- في عمليات الربط غير loopback: تتطلب مسارات canvas مصادقة البوابة (token/password/trusted-proxy)، مثلها مثل أسطح HTTP الأخرى للبوابة. +- لا ترسل Node WebViews عادةً ترويسات المصادقة؛ وبعد إقران عقدة واتصالها، تعلن البوابة عناوين URL للقدرات ضمن نطاق العقدة للوصول إلى canvas/A2UI. +- ترتبط عناوين URL الخاصة بالقدرات بجلسة WS النشطة للعقدة وتنتهي صلاحيتها سريعاً. ولا يُستخدم الرجوع الاحتياطي المعتمد على IP. +- يحقن عميل live-reload في HTML المقدم. +- ينشئ تلقائياً ملف `index.html` ابتدائياً عند الفراغ. +- يقدّم أيضاً A2UI على `/__openclaw__/a2ui/`. - تتطلب التغييرات إعادة تشغيل البوابة. - عطّل live reload للأدلة الكبيرة أو عند أخطاء `EMFILE`. @@ -2548,14 +3179,32 @@ __OC_I18N_900083__ ## الاكتشاف ### mDNS ‏(Bonjour) -__OC_I18N_900084__ + +```json5 +{ + discovery: { + mdns: { + mode: "minimal", // minimal | full | off + }, + }, +} +``` + - `minimal` (الافتراضي): يحذف `cliPath` + `sshPort` من سجلات TXT. - `full`: يتضمن `cliPath` + `sshPort`. -- يكون اسم المضيف افتراضيًا `openclaw`. تجاوزه باستخدام `OPENCLAW_MDNS_HOSTNAME`. +- يكون اسم المضيف افتراضياً `openclaw`. ويمكن تجاوزه عبر `OPENCLAW_MDNS_HOSTNAME`. -### Wide-area ‏(DNS-SD) -__OC_I18N_900085__ -يكتب منطقة DNS-SD أحادية الإرسال تحت `~/.openclaw/dns/`. وللاكتشاف عبر الشبكات، أقرنه مع خادم DNS ‏(يُوصى بـ CoreDNS) + Tailscale split DNS. +### واسع النطاق ‏(DNS-SD) + +```json5 +{ + discovery: { + wideArea: { enabled: true }, + }, +} +``` + +يكتب منطقة DNS-SD أحادية الإرسال ضمن `~/.openclaw/dns/`. وللاكتشاف عبر الشبكات، أقرنه بخادم DNS ‏(يُوصى بـ CoreDNS) + ‏Tailscale split DNS. الإعداد: `openclaw dns setup --apply`. @@ -2563,123 +3212,270 @@ __OC_I18N_900085__ ## البيئة -### `env` ‏(متغيرات البيئة المضمنة) -__OC_I18N_900086__ -- لا تُطبّق متغيرات البيئة المضمنة إلا إذا كانت بيئة العملية تفتقد ذلك المفتاح. -- ملفات `.env`: ‏`.env` في CWD + ‏`~/.openclaw/.env` (ولا يطغى أي منهما على المتغيرات الموجودة). -- `shellEnv`: يستورد المفاتيح المتوقعة المفقودة من ملف تعريف صدفة تسجيل الدخول لديك. -- راجع [البيئة](/help/environment) لمعرفة الأسبقية الكاملة. +### `env` (متغيرات البيئة المضمنة) -### الاستبدال بمتغيرات البيئة +```json5 +{ + env: { + OPENROUTER_API_KEY: "sk-or-...", + vars: { + GROQ_API_KEY: "gsk-...", + }, + shellEnv: { + enabled: true, + timeoutMs: 15000, + }, + }, +} +``` -أشر إلى متغيرات البيئة في أي سلسلة إعدادات باستخدام `${VAR_NAME}`: -__OC_I18N_900087__ -- لا تُطابق إلا الأسماء المكتوبة بالأحرف الكبيرة: `[A-Z_][A-Z0-9_]*`. -- تؤدي المتغيرات المفقودة/الفارغة إلى إطلاق خطأ عند تحميل الإعدادات. -- اهرب باستخدام `$${VAR}` للحصول على `${VAR}` حرفيًا. -- يعمل أيضًا مع `$include`. +- لا تُطبّق متغيرات البيئة المضمنة إلا إذا كانت بيئة العملية تفتقد المفتاح. +- ملفات `.env`: ملف `.env` في CWD + الملف `~/.openclaw/.env` (ولا يتجاوز أي منهما المتغيرات الموجودة). +- `shellEnv`: يستورد المفاتيح المتوقعة المفقودة من ملف تعريف login shell لديك. +- راجع [البيئة](/ar/help/environment) لمعرفة الأسبقية الكاملة. + +### استبدال متغيرات البيئة + +ارجع إلى متغيرات البيئة في أي سلسلة إعداد باستخدام `${VAR_NAME}`: + +```json5 +{ + gateway: { + auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" }, + }, +} +``` + +- تتم مطابقة الأسماء الكبيرة فقط: `[A-Z_][A-Z0-9_]*`. +- تؤدي المتغيرات المفقودة/الفارغة إلى رمي خطأ عند تحميل الإعداد. +- استخدم `$${VAR}` للحصول على `${VAR}` حرفياً. +- يعمل ذلك مع `$include`. --- ## الأسرار -إشارات السر Secret refs إضافية: لا تزال القيم النصية الصريحة تعمل. +تُعد مراجع الأسرار إضافية: ولا تزال القيم النصية الصريحة تعمل. ### `SecretRef` -استخدم شكل كائن واحد: -__OC_I18N_900088__ +استخدم شكل كائن واحداً: + +```json5 +{ source: "env" | "file" | "exec", provider: "default", id: "..." } +``` + التحقق: - نمط `provider`: ‏`^[a-z][a-z0-9_-]{0,63}$` - نمط `id` عند `source: "env"`: ‏`^[A-Z][A-Z0-9_]{0,127}$` -- `source: "file"` ‏`id`: مؤشر JSON مطلق (مثل `"/providers/openai/apiKey"`) +- `source: "file"` ‏`id`: مؤشر JSON مطلق (مثلاً `"/providers/openai/apiKey"`) - نمط `id` عند `source: "exec"`: ‏`^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` -- يجب ألا تحتوي معرّفات `source: "exec"` على مقاطع مسار مفصولة بشرطة مائلة من نوع `.` أو `..` (على سبيل المثال يُرفض `a/../b`) +- يجب ألا تحتوي معرّفات `source: "exec"` على مقاطع مسار `.` أو `..` مفصولة بشرطة مائلة (مثلاً `a/../b` مرفوض) ### سطح بيانات الاعتماد المدعوم -- المصفوفة القياسية: [سطح بيانات اعتماد SecretRef](/reference/secretref-credential-surface) +- المصفوفة القياسية: [سطح بيانات اعتماد SecretRef](/ar/reference/secretref-credential-surface) - تستهدف `secrets apply` مسارات بيانات الاعتماد المدعومة في `openclaw.json`. -- تُدرج إشارات `auth-profiles.json` في حل وقت التشغيل وتغطية التدقيق. +- تُدرج مراجع `auth-profiles.json` في حل وقت التشغيل وتغطية التدقيق. + +### إعداد موفّري الأسرار + +```json5 +{ + secrets: { + providers: { + default: { source: "env" }, // optional explicit env provider + filemain: { + source: "file", + path: "~/.openclaw/secrets.json", + mode: "json", + timeoutMs: 5000, + }, + vault: { + source: "exec", + command: "/usr/local/bin/openclaw-vault-resolver", + passEnv: ["PATH", "VAULT_ADDR"], + }, + }, + defaults: { + env: "default", + file: "filemain", + exec: "vault", + }, + }, +} +``` -### إعدادات موفري الأسرار -__OC_I18N_900089__ ملاحظات: -- يدعم موفر `file` الوضعين `mode: "json"` و`mode: "singleValue"` (ويجب أن تكون `id` مساوية لـ `"value"` في وضع singleValue). -- يتطلب موفر `exec` مسار `command` مطلقًا ويستخدم حمولات بروتوكول على stdin/stdout. -- تُرفض مسارات أوامر الروابط الرمزية افتراضيًا. عيّن `allowSymlinkCommand: true` للسماح بمسارات الروابط الرمزية مع التحقق من المسار الهدف المحلول. -- إذا تم إعداد `trustedDirs`، فيُطبّق فحص الدليل الموثوق على المسار الهدف المحلول. -- تكون بيئة الابن لـ `exec` دنيا افتراضيًا؛ مرّر المتغيرات المطلوبة صراحةً باستخدام `passEnv`. -- تُحل Secret refs وقت التفعيل إلى لقطة موجودة في الذاكرة، ثم تقرأ مسارات الطلب من اللقطة فقط. -- يُطبّق ترشيح السطح النشط أثناء التفعيل: تؤدي الإشارات غير المحلولة على الأسطح المفعّلة إلى فشل بدء التشغيل/إعادة التحميل، بينما تُتخطى الأسطح غير النشطة مع تشخيصات. +- يدعم موفّر `file` الوضعين `mode: "json"` و`mode: "singleValue"` (ويجب أن تكون `id` هي `"value"` في وضع singleValue). +- يتطلب موفّر `exec` مسار `command` مطلقاً ويستخدم حمولات البروتوكول على stdin/stdout. +- تُرفض مسارات الأوامر الرمزية افتراضياً. اضبط `allowSymlinkCommand: true` للسماح بمسارات الروابط الرمزية مع التحقق من مسار الهدف المحلول. +- إذا تم إعداد `trustedDirs`، فيُطبَّق فحص الدليل الموثوق على مسار الهدف المحلول. +- تكون بيئة عملية الابن لـ `exec` محدودة افتراضياً؛ مرّر المتغيرات المطلوبة صراحةً عبر `passEnv`. +- تُحل مراجع الأسرار وقت التفعيل إلى لقطة داخل الذاكرة، ثم تقرأ مسارات الطلب تلك اللقطة فقط. +- يُطبّق ترشيح السطح النشط أثناء التفعيل: تؤدي المراجع غير المحلولة على الأسطح المفعلة إلى فشل بدء التشغيل/إعادة التحميل، بينما يتم تخطي الأسطح غير النشطة مع تشخيصات. --- ## تخزين المصادقة -__OC_I18N_900090__ -- تُخزَّن الملفات الشخصية لكل وكيل في `/auth-profiles.json`. -- يدعم `auth-profiles.json` إشارات على مستوى القيمة (`keyRef` لـ `api_key`، و`tokenRef` لـ `token`) لأنماط بيانات الاعتماد الثابتة. -- لا تدعم الملفات الشخصية ذات وضع OAuth ‏(`auth.profiles..mode = "oauth"`) بيانات اعتماد الملفات الشخصية للمصادقة المدعومة بـ SecretRef. -- تأتي بيانات الاعتماد الثابتة وقت التشغيل من لقطات محلولة داخل الذاكرة؛ وتُنظَّف إدخالات `auth.json` الثابتة القديمة عند اكتشافها. -- الواردات القديمة لـ OAuth من `~/.openclaw/credentials/oauth.json`. -- راجع [OAuth](/concepts/oauth). -- سلوك وقت تشغيل الأسرار وأدوات `audit/configure/apply`: ‏[إدارة الأسرار](/gateway/secrets). + +```json5 +{ + auth: { + profiles: { + "anthropic:default": { provider: "anthropic", mode: "api_key" }, + "anthropic:work": { provider: "anthropic", mode: "api_key" }, + "openai-codex:personal": { provider: "openai-codex", mode: "oauth" }, + }, + order: { + anthropic: ["anthropic:default", "anthropic:work"], + "openai-codex": ["openai-codex:personal"], + }, + }, +} +``` + +- تُخزّن الملفات التعريفية لكل وكيل في `/auth-profiles.json`. +- يدعم `auth-profiles.json` المراجع على مستوى القيمة (`keyRef` لـ `api_key`، و`tokenRef` لـ `token`) لأوضاع بيانات الاعتماد الثابتة. +- لا تدعم الملفات التعريفية في وضع OAuth ‏(`auth.profiles..mode = "oauth"`) بيانات اعتماد auth-profile المدعومة بـ SecretRef. +- تأتي بيانات الاعتماد الثابتة لوقت التشغيل من لقطات محلولة داخل الذاكرة؛ وتُنظَّف إدخالات `auth.json` الثابتة القديمة عند اكتشافها. +- يتم استيراد OAuth القديم من `~/.openclaw/credentials/oauth.json`. +- راجع [OAuth](/ar/concepts/oauth). +- سلوك وقت تشغيل الأسرار وأدوات `audit/configure/apply`: ‏[إدارة الأسرار](/ar/gateway/secrets). ### `auth.cooldowns` -__OC_I18N_900091__ -- `billingBackoffHours`: مدة التراجع الأساسية بالساعات عند فشل ملف شخصي بسبب أخطاء حقيقية تتعلق بالفوترة/عدم كفاية الرصيد - (الافتراضي: `5`). لا يزال من الممكن أن تصل نصوص الفوترة الصريحة - إلى هذا المسار حتى مع استجابات `401`/`403`، لكن أدوات المطابقة النصية - الخاصة بكل موفر تظل محصورة في الموفر الذي يملكها (على سبيل المثال OpenRouter - `Key limit exceeded`). أما رسائل حد إنفاق - نافذة الاستخدام القابلة لإعادة المحاولة في HTTP `402` أو الخاصة بالمؤسسة/مساحة العمل - فتظل في مسار `rate_limit` بدلًا من ذلك. -- `billingBackoffHoursByProvider`: تجاوزات اختيارية لكل موفر لساعات تراجع الفوترة. -- `billingMaxHours`: الحد الأقصى بالساعات للنمو الأسي لتراجع الفوترة (الافتراضي: `24`). -- `authPermanentBackoffMinutes`: مدة التراجع الأساسية بالدقائق لإخفاقات `auth_permanent` عالية الثقة (الافتراضي: `10`). -- `authPermanentMaxMinutes`: الحد الأقصى بالدقائق لنمو تراجع `auth_permanent` (الافتراضي: `60`). -- `failureWindowHours`: نافذة متحركة بالساعات تُستخدم لعدادات التراجع (الافتراضي: `24`). -- `overloadedProfileRotations`: الحد الأقصى لعمليات تدوير ملفات المصادقة ضمن الموفر نفسه لأخطاء الحمل الزائد قبل التبديل إلى احتياطي النموذج (الافتراضي: `1`). وتدخل هنا أشكال انشغال الموفر مثل `ModelNotReadyException`. -- `overloadedBackoffMs`: تأخير ثابت قبل إعادة محاولة تدوير ملف/موفر محمّل زيادةً عن الحد (الافتراضي: `0`). -- `rateLimitedProfileRotations`: الحد الأقصى لعمليات تدوير ملفات المصادقة ضمن الموفر نفسه لأخطاء تحديد المعدل قبل التبديل إلى احتياطي النموذج (الافتراضي: `1`). وتشمل فئة تحديد المعدل نصوصًا خاصة بالموفر مثل `Too many concurrent requests` و`ThrottlingException` و`concurrency limit reached` و`workers_ai ... quota limit exceeded` و`resource exhausted`. + +```json5 +{ + auth: { + cooldowns: { + billingBackoffHours: 5, + billingBackoffHoursByProvider: { anthropic: 3, openai: 8 }, + billingMaxHours: 24, + authPermanentBackoffMinutes: 10, + authPermanentMaxMinutes: 60, + failureWindowHours: 24, + overloadedProfileRotations: 1, + overloadedBackoffMs: 0, + rateLimitedProfileRotations: 1, + }, + }, +} +``` + +- `billingBackoffHours`: مدة backoff الأساسية بالساعات عندما يفشل ملف تعريفي بسبب + أخطاء حقيقية في الفوترة/عدم كفاية الرصيد (الافتراضي: `5`). ويمكن للنص الصريح + الخاص بالفوترة أن يقع هنا حتى في استجابات `401`/`403`، لكن مطابِقات النصوص + الخاصة بكل موفّر تبقى محصورة في الموفّر الذي يملكها (مثلاً OpenRouter + `Key limit exceeded`). بينما تبقى رسائل `402` القابلة لإعادة المحاولة الخاصة + بنافذة الاستخدام أو حد الإنفاق الخاص بالمؤسسة/مساحة العمل ضمن مسار `rate_limit` + بدلاً من ذلك. +- `billingBackoffHoursByProvider`: تجاوزات اختيارية لكل موفّر لساعات backoff الخاصة بالفوترة. +- `billingMaxHours`: الحد الأقصى بالساعات للنمو الأسي لـ backoff الفوترة (الافتراضي: `24`). +- `authPermanentBackoffMinutes`: مدة backoff الأساسية بالدقائق لإخفاقات `auth_permanent` عالية الثقة (الافتراضي: `10`). +- `authPermanentMaxMinutes`: الحد الأقصى بالدقائق لنمو backoff الخاص بـ `auth_permanent` (الافتراضي: `60`). +- `failureWindowHours`: نافذة متحركة بالساعات تُستخدم لعدادات backoff (الافتراضي: `24`). +- `overloadedProfileRotations`: الحد الأقصى لعمليات تدوير auth-profile ضمن الموفّر نفسه لأخطاء التحميل الزائد قبل التبديل إلى النموذج الاحتياطي (الافتراضي: `1`). وتقع هنا أشكال انشغال الموفّر مثل `ModelNotReadyException`. +- `overloadedBackoffMs`: تأخير ثابت قبل إعادة محاولة تدوير موفّر/ملف تعريفي محمّل فوق طاقته (الافتراضي: `0`). +- `rateLimitedProfileRotations`: الحد الأقصى لعمليات تدوير auth-profile ضمن الموفّر نفسه لأخطاء تحديد المعدل قبل التبديل إلى النموذج الاحتياطي (الافتراضي: `1`). ويتضمن مسار تحديد المعدل هذا نصوصاً ذات شكل خاص بالموفّر مثل `Too many concurrent requests` و`ThrottlingException` و`concurrency limit reached` و`workers_ai ... quota limit exceeded` و`resource exhausted`. --- ## التسجيل -__OC_I18N_900092__ + +```json5 +{ + logging: { + level: "info", + file: "/tmp/openclaw/openclaw.log", + consoleLevel: "info", + consoleStyle: "pretty", // pretty | compact | json + redactSensitive: "tools", // off | tools + redactPatterns: ["\\bTOKEN\\b\\s*[=:]\\s*([\"']?)([^\\s\"']+)\\1"], + }, +} +``` + - ملف السجل الافتراضي: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`. -- عيّن `logging.file` لمسار ثابت. +- اضبط `logging.file` لمسار ثابت. - يرتفع `consoleLevel` إلى `debug` عند `--verbose`. -- `maxFileBytes`: الحد الأقصى لحجم ملف السجل بالبايت قبل كبت عمليات الكتابة (عدد صحيح موجب؛ الافتراضي: `524288000` = ‏500 MB). استخدم تدوير سجلات خارجيًا لعمليات النشر الإنتاجية. +- `maxFileBytes`: الحد الأقصى لحجم ملف السجل بالبايت قبل كبح عمليات الكتابة (عدد صحيح موجب؛ الافتراضي: `524288000` = ‏500 MB). استخدم تدوير السجلات الخارجي في بيئات الإنتاج. --- -## التشخيصات -__OC_I18N_900093__ -- `enabled`: المفتاح الرئيسي لمخرجات القياس/الأدوات (الافتراضي: `true`). -- `flags`: مصفوفة من سلاسل الأعلام تفعّل مخرجات السجل الموجّهة (وتدعم أحرف البدل مثل `"telegram.*"` أو `"*"`). -- `stuckSessionWarnMs`: عتبة العمر بالمللي ثانية لإصدار تحذيرات الجلسات العالقة بينما تبقى الجلسة في حالة المعالجة. +## التشخيص + +```json5 +{ + diagnostics: { + enabled: true, + flags: ["telegram.*"], + stuckSessionWarnMs: 30000, + + otel: { + enabled: false, + endpoint: "https://otel-collector.example.com:4318", + protocol: "http/protobuf", // http/protobuf | grpc + headers: { "x-tenant-id": "my-org" }, + serviceName: "openclaw-gateway", + traces: true, + metrics: true, + logs: false, + sampleRate: 1.0, + flushIntervalMs: 5000, + }, + + cacheTrace: { + enabled: false, + filePath: "~/.openclaw/logs/cache-trace.jsonl", + includeMessages: true, + includePrompt: true, + includeSystem: true, + }, + }, +} +``` + +- `enabled`: المفتاح الرئيسي لمخرجات أدوات القياس (الافتراضي: `true`). +- `flags`: مصفوفة من سلاسل الأعلام التي تفعّل مخرجات سجل موجّهة (وتدعم أحرف البدل مثل `"telegram.*"` أو `"*"`). +- `stuckSessionWarnMs`: عتبة العمر بالمللي ثانية لإصدار تحذيرات الجلسة العالقة بينما تظل الجلسة في حالة المعالجة. - `otel.enabled`: يفعّل مسار تصدير OpenTelemetry ‏(الافتراضي: `false`). -- `otel.endpoint`: عنوان URL للمجمّع الخاص بتصدير OTel. +- `otel.endpoint`: عنوان URL للمجمّع من أجل تصدير OTel. - `otel.protocol`: ‏`"http/protobuf"` (الافتراضي) أو `"grpc"`. -- `otel.headers`: ترويسات HTTP/gRPC metadata إضافية تُرسل مع طلبات تصدير OTel. -- `otel.serviceName`: اسم الخدمة لسمات الموارد. +- `otel.headers`: ترويسات بيانات وصفية إضافية لـ HTTP/gRPC تُرسل مع طلبات تصدير OTel. +- `otel.serviceName`: اسم الخدمة لسمات المورد. - `otel.traces` / `otel.metrics` / `otel.logs`: تفعيل تصدير التتبعات أو المقاييس أو السجلات. - `otel.sampleRate`: معدل أخذ عينات التتبعات من `0` إلى `1`. -- `otel.flushIntervalMs`: فاصل التفريغ الدوري لبيانات القياس عن بُعد بالمللي ثانية. -- `cacheTrace.enabled`: يسجل لقطات تتبع cache للتشغيلات المضمّنة (الافتراضي: `false`). -- `cacheTrace.filePath`: مسار الخرج لملف cache trace بصيغة JSONL ‏(الافتراضي: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). -- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: تتحكم فيما يُضمَّن في خرج cache trace (وجميعها افتراضيًا: `true`). +- `otel.flushIntervalMs`: فاصل التفريغ الدوري للقياسات بالمللي ثانية. +- `cacheTrace.enabled`: يسجل لقطات تتبع الذاكرة المؤقتة للتشغيلات المضمنة (الافتراضي: `false`). +- `cacheTrace.filePath`: مسار الإخراج لملف JSONL الخاص بتتبع الذاكرة المؤقتة (الافتراضي: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). +- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: تتحكم في ما يتم تضمينه في مخرجات تتبع الذاكرة المؤقتة (وجميعها افتراضياً: `true`). --- ## التحديث -__OC_I18N_900094__ -- `channel`: قناة الإصدار لعمليات تثبيت npm/git — ‏`"stable"` أو `"beta"` أو `"dev"`. -- `checkOnStart`: التحقق من تحديثات npm عند بدء تشغيل البوابة (الافتراضي: `true`). -- `auto.enabled`: يفعّل التحديث التلقائي في الخلفية لعمليات تثبيت الحزم (الافتراضي: `false`). + +```json5 +{ + update: { + channel: "stable", // stable | beta | dev + checkOnStart: true, + + auto: { + enabled: false, + stableDelayHours: 6, + stableJitterHours: 12, + betaCheckIntervalHours: 1, + }, + }, +} +``` + +- `channel`: قناة الإصدار لتثبيتات npm/git — ‏`"stable"` أو `"beta"` أو `"dev"`. +- `checkOnStart`: التحقق من تحديثات npm عند بدء البوابة (الافتراضي: `true`). +- `auto.enabled`: تفعيل التحديث التلقائي في الخلفية لتثبيتات الحزم (الافتراضي: `false`). - `auto.stableDelayHours`: الحد الأدنى للتأخير بالساعات قبل التطبيق التلقائي لقناة stable ‏(الافتراضي: `6`؛ الحد الأقصى: `168`). - `auto.stableJitterHours`: نافذة توزيع إضافية بالساعات لطرح قناة stable ‏(الافتراضي: `12`؛ الحد الأقصى: `168`). - `auto.betaCheckIntervalHours`: عدد مرات تشغيل فحوصات قناة beta بالساعات (الافتراضي: `1`؛ الحد الأقصى: `24`). @@ -2687,106 +3483,224 @@ __OC_I18N_900094__ --- ## ACP -__OC_I18N_900095__ -- `enabled`: بوابة الميزات العامة لـ ACP ‏(الافتراضي: `false`). -- `dispatch.enabled`: بوابة مستقلة لإرسال أدوار جلسات ACP ‏(الافتراضي: `true`). عيّنها إلى `false` للإبقاء على أوامر ACP متاحة مع حظر التنفيذ. -- `backend`: معرّف الخلفية الافتراضية لوقت تشغيل ACP ‏(ويجب أن يطابق plugin وقت تشغيل ACP مسجلًا). -- `defaultAgent`: معرّف وكيل ACP الاحتياطي المستهدف عندما لا تحدد عمليات الإنشاء هدفًا صريحًا. + +```json5 +{ + acp: { + enabled: false, + dispatch: { enabled: true }, + backend: "acpx", + defaultAgent: "main", + allowedAgents: ["main", "ops"], + maxConcurrentSessions: 10, + + stream: { + coalesceIdleMs: 50, + maxChunkChars: 1000, + repeatSuppression: true, + deliveryMode: "live", // live | final_only + hiddenBoundarySeparator: "paragraph", // none | space | newline | paragraph + maxOutputChars: 50000, + maxSessionUpdateChars: 500, + }, + + runtime: { + ttlMinutes: 30, + }, + }, +} +``` + +- `enabled`: بوابة الميزة العامة لـ ACP ‏(الافتراضي: `false`). +- `dispatch.enabled`: بوابة مستقلة لتوزيع أدوار جلسات ACP ‏(الافتراضي: `true`). اضبطها على `false` للإبقاء على أوامر ACP متاحة مع حظر التنفيذ. +- `backend`: معرّف الواجهة الخلفية الافتراضية لوقت تشغيل ACP ‏(ويجب أن يطابق ACP runtime plugin مسجلاً). +- `defaultAgent`: معرّف وكيل ACP الاحتياطي المستهدف عندما لا تحدد عمليات الإنشاء هدفاً صريحاً. - `allowedAgents`: قائمة سماح لمعرّفات الوكلاء المسموح بها لجلسات وقت تشغيل ACP؛ وتعني القيمة الفارغة عدم وجود تقييد إضافي. -- `maxConcurrentSessions`: الحد الأقصى لعدد جلسات ACP النشطة بالتوازي. +- `maxConcurrentSessions`: الحد الأقصى لعدد جلسات ACP النشطة بالتزامن. - `stream.coalesceIdleMs`: نافذة التفريغ عند الخمول بالمللي ثانية للنص المتدفق. -- `stream.maxChunkChars`: الحد الأقصى لحجم الكتلة قبل تقسيم إسقاط الكتلة المتدفقة. -- `stream.repeatSuppression`: يمنع تكرار أسطر الحالة/الأدوات لكل دور (الافتراضي: `true`). -- `stream.deliveryMode`: تؤدي `"live"` إلى البث التدريجي؛ وتؤدي `"final_only"` إلى التخزين المؤقت حتى أحداث نهاية الدور. +- `stream.maxChunkChars`: الحد الأقصى لحجم الجزء قبل تقسيم إسقاط الكتلة المتدفقة. +- `stream.repeatSuppression`: يحجب أسطر الحالة/الأدوات المكررة لكل دور (الافتراضي: `true`). +- `stream.deliveryMode`: ‏`"live"` يبث تدريجياً؛ بينما `final_only` يخزن مؤقتاً حتى الأحداث النهائية للدور. - `stream.hiddenBoundarySeparator`: الفاصل قبل النص المرئي بعد أحداث الأدوات المخفية (الافتراضي: `"paragraph"`). -- `stream.maxOutputChars`: الحد الأقصى لأحرف خرج المساعد المُسقطة لكل دور ACP. -- `stream.maxSessionUpdateChars`: الحد الأقصى لأحرف أسطر الحالة/التحديث المسقطة لـ ACP. -- `stream.tagVisibility`: سجلّ لأسماء الوسوم إلى تجاوزات رؤية منطقية للأحداث المتدفقة. -- `runtime.ttlMinutes`: مدة TTL للخمول بالدقائق لعُمّال جلسات ACP قبل أن يصبحوا مؤهلين للتنظيف. -- `runtime.installCommand`: أمر تثبيت اختياري يُشغَّل عند تهيئة بيئة وقت تشغيل ACP. +- `stream.maxOutputChars`: الحد الأقصى لأحرف مخرجات المساعد المسقطة لكل دور ACP. +- `stream.maxSessionUpdateChars`: الحد الأقصى للأحرف في أسطر الحالة/التحديث المسقطة الخاصة بـ ACP. +- `stream.tagVisibility`: سجل لأسماء الوسوم إلى تجاوزات رؤية منطقية للأحداث المتدفقة. +- `runtime.ttlMinutes`: مدة TTL للخمول بالدقائق لعمّال جلسات ACP قبل أن يصبحوا مؤهلين للتنظيف. +- `runtime.installCommand`: أمر تثبيت اختياري للتشغيل عند تهيئة بيئة وقت تشغيل ACP. --- ## CLI -__OC_I18N_900096__ -- يتحكم `cli.banner.taglineMode` في نمط الشعار النصي في banner: - - `"random"` (الافتراضي): شعارات نصية مضحكة/موسمية متناوبة. - - `"default"`: شعار نصي ثابت ومحايد (`All your chats, one OpenClaw.`). - - `"off"`: بدون نص شعار (مع استمرار عرض عنوان banner/الإصدار). -- لإخفاء banner بالكامل (وليس الشعارات النصية فقط)، عيّن متغير البيئة `OPENCLAW_HIDE_BANNER=1`. + +```json5 +{ + cli: { + banner: { + taglineMode: "off", // random | default | off + }, + }, +} +``` + +- يتحكم `cli.banner.taglineMode` في أسلوب الشعار النصي: + - `"random"` (الافتراضي): شعارات نصية متناوبة طريفة/موسمية. + - `"default"`: شعار نصي ثابت ومحايد (`كل محادثاتك، OpenClaw واحد.`). + - `"off"`: بدون نص شعار (مع استمرار عرض عنوان اللافتة/الإصدار). +- لإخفاء اللافتة بالكامل (وليس فقط الشعارات النصية)، اضبط متغير البيئة `OPENCLAW_HIDE_BANNER=1`. --- -## Wizard +## المعالج + +بيانات وصفية يكتبها CLI أثناء تدفقات الإعداد الموجهة (`onboard` و`configure` و`doctor`): + +```json5 +{ + wizard: { + lastRunAt: "2026-01-01T00:00:00.000Z", + lastRunVersion: "2026.1.4", + lastRunCommit: "abc1234", + lastRunCommand: "configure", + lastRunMode: "local", + }, +} +``` -بيانات وصفية يكتبها CLI في تدفقات الإعداد الموجّهة (`onboard` و`configure` و`doctor`): -__OC_I18N_900097__ --- ## الهوية -راجع حقول الهوية في `agents.list` تحت [القيم الافتراضية للوكلاء](#agent-defaults). +راجع حقول الهوية في `agents.list` ضمن [القيم الافتراضية للوكلاء](#agent-defaults). --- -## Bridge ‏(قديم، أزيل) +## Bridge ‏(قديم، تمت إزالته) -لم تعد الإصدارات الحالية تتضمن TCP bridge. وتتصل Nodes عبر Gateway WebSocket. ولم تعد مفاتيح `bridge.*` جزءًا من مخطط الإعدادات (وسيفشل التحقق حتى تُزال؛ ويمكن لـ `openclaw doctor --fix` حذف المفاتيح غير المعروفة). +لم تعد الإصدارات الحالية تتضمن TCP bridge. تتصل العقد عبر WebSocket الخاص بالبوابة. ولم تعد مفاتيح `bridge.*` جزءاً من مخطط الإعدادات (وسيفشل التحقق حتى تتم إزالتها؛ ويمكن لـ `openclaw doctor --fix` إزالة المفاتيح غير المعروفة). -__OC_I18N_900098__ + +```json +{ + "bridge": { + "enabled": true, + "port": 18790, + "bind": "tailnet", + "tls": { + "enabled": true, + "autoGenerate": true + } + } +} +``` + --- ## Cron -__OC_I18N_900099__ -- `sessionRetention`: مدة الاحتفاظ بجلسات تشغيل cron المعزولة المكتملة قبل حذفها من `sessions.json`. كما تتحكم أيضًا في تنظيف نصوص cron المؤرشفة المحذوفة. الافتراضي: `24h`؛ عيّن `false` للتعطيل. -- `runLog.maxBytes`: الحجم الأقصى لكل ملف سجل تشغيل (`cron/runs/.jsonl`) قبل الحذف. الافتراضي: `2_000_000` بايت. -- `runLog.keepLines`: أحدث الأسطر المحتفَظ بها عند تشغيل حذف سجل التشغيل. الافتراضي: `2000`. -- `webhookToken`: رمز bearer المميز المستخدم لتسليم POST إلى webhook في cron ‏(`delivery.mode = "webhook"`)، وإذا حُذف لا تُرسل أي ترويسة مصادقة. -- `webhook`: عنوان URL احتياطي قديم لـ webhook ‏(http/https) يُستخدم فقط للمهام المخزنة التي ما زال لديها `notify: true`. + +```json5 +{ + cron: { + enabled: true, + maxConcurrentRuns: 2, + webhook: "https://example.invalid/legacy", // deprecated fallback for stored notify:true jobs + webhookToken: "replace-with-dedicated-token", // optional bearer token for outbound webhook auth + sessionRetention: "24h", // duration string or false + runLog: { + maxBytes: "2mb", // default 2_000_000 bytes + keepLines: 2000, // default 2000 + }, + }, +} +``` + +- `sessionRetention`: المدة التي تُحتفظ خلالها بجلسات تشغيل cron المعزولة المكتملة قبل اقتطاعها من `sessions.json`. كما تتحكم أيضاً في تنظيف نُسخ نصوص cron المحذوفة المؤرشفة. الافتراضي: `24h`؛ واضبطها على `false` للتعطيل. +- `runLog.maxBytes`: الحد الأقصى للحجم لكل ملف سجل تشغيل (`cron/runs/.jsonl`) قبل الاقتطاع. الافتراضي: `2_000_000` بايت. +- `runLog.keepLines`: أحدث الأسطر التي يتم الاحتفاظ بها عند تشغيل اقتطاع سجل التشغيل. الافتراضي: `2000`. +- `webhookToken`: رمز bearer يُستخدم في تسليم POST إلى webhook الخاص بـ cron ‏(`delivery.mode = "webhook"`). وإذا حُذف، لا يتم إرسال ترويسة مصادقة. +- `webhook`: عنوان URL قديم ومهجور لـ webhook ‏(http/https) يُستخدم فقط للوظائف المخزنة التي ما زالت تحتوي على `notify: true`. ### `cron.retry` -__OC_I18N_900100__ -- `maxAttempts`: الحد الأقصى لإعادات المحاولة للمهام أحادية التشغيل عند حدوث أخطاء عابرة (الافتراضي: `3`؛ النطاق: `0`–`10`). -- `backoffMs`: مصفوفة تأخيرات التراجع بالمللي ثانية لكل محاولة إعادة (الافتراضي: `[30000, 60000, 300000]`؛ من 1 إلى 10 إدخالات). -- `retryOn`: أنواع الأخطاء التي تؤدي إلى إعادة المحاولة — ‏`"rate_limit"` و`"overloaded"` و`"network"` و`"timeout"` و`"server_error"`. احذفها لإعادة المحاولة مع جميع الأنواع العابرة. -ينطبق ذلك فقط على مهام cron أحادية التشغيل. أما المهام المتكررة فلها معالجة إخفاق منفصلة. +```json5 +{ + cron: { + retry: { + maxAttempts: 3, + backoffMs: [30000, 60000, 300000], + retryOn: ["rate_limit", "overloaded", "network", "timeout", "server_error"], + }, + }, +} +``` + +- `maxAttempts`: الحد الأقصى لإعادات المحاولة للوظائف ذات التشغيل الواحد عند الأخطاء العابرة (الافتراضي: `3`؛ النطاق: `0`–`10`). +- `backoffMs`: مصفوفة تأخيرات backoff بالمللي ثانية لكل محاولة إعادة (الافتراضي: `[30000, 60000, 300000]`؛ من 1 إلى 10 إدخالات). +- `retryOn`: أنواع الأخطاء التي تؤدي إلى إعادة المحاولة — `"rate_limit"` و`"overloaded"` و`"network"` و`"timeout"` و`"server_error"`. احذفها لإعادة المحاولة مع جميع الأنواع العابرة. + +ينطبق هذا فقط على وظائف cron ذات التشغيل الواحد. أما الوظائف المتكررة فلها معالجة إخفاقات منفصلة. ### `cron.failureAlert` -__OC_I18N_900101__ -- `enabled`: تفعيل تنبيهات الإخفاق لمهام cron ‏(الافتراضي: `false`). + +```json5 +{ + cron: { + failureAlert: { + enabled: false, + after: 3, + cooldownMs: 3600000, + mode: "announce", + accountId: "main", + }, + }, +} +``` + +- `enabled`: يفعّل تنبيهات الفشل لوظائف cron ‏(الافتراضي: `false`). - `after`: عدد الإخفاقات المتتالية قبل إطلاق التنبيه (عدد صحيح موجب، الحد الأدنى: `1`). -- `cooldownMs`: الحد الأدنى بالمللي ثانية بين التنبيهات المتكررة للمهمة نفسها (عدد صحيح غير سالب). -- `mode`: وضع التسليم — تؤدي `"announce"` إلى الإرسال عبر رسالة قناة؛ وتؤدي `"webhook"` إلى POST إلى webhook المُعد. +- `cooldownMs`: الحد الأدنى بالمللي ثانية بين التنبيهات المتكررة لنفس الوظيفة (عدد صحيح غير سالب). +- `mode`: وضع التسليم — ترسل `"announce"` عبر رسالة قناة؛ بينما تنشر `"webhook"` إلى webhook المُعد. - `accountId`: معرّف حساب أو قناة اختياري لتحديد نطاق تسليم التنبيه. ### `cron.failureDestination` -__OC_I18N_900102__ -- الوجهة الافتراضية لإشعارات إخفاق cron عبر جميع المهام. -- `mode`: ‏`"announce"` أو `"webhook"`؛ وتكون القيمة الافتراضية `"announce"` عندما تتوفر بيانات هدف كافية. -- `channel`: تجاوز القناة لتسليم announce. وتعيد `"last"` استخدام آخر قناة تسليم معروفة. -- `to`: هدف announce صريح أو عنوان URL لـ webhook. وهو مطلوب في وضع webhook. -- `accountId`: تجاوز حساب اختياري للتسليم. -- يتجاوز `delivery.failureDestination` لكل مهمة هذا الإعداد الافتراضي العام. -- عندما لا يتم تعيين وجهة إخفاق عامة ولا لكل مهمة، تعود المهام التي تسلّم أصلًا عبر `announce` احتياطيًا إلى ذلك الهدف الأساسي لـ announce عند الإخفاق. -- لا يُدعم `delivery.failureDestination` إلا لمهام `sessionTarget="isolated"` ما لم يكن `delivery.mode` الأساسي للمهمة هو `"webhook"`. -راجع [وظائف Cron](/automation/cron-jobs). ويتم تتبع عمليات تنفيذ cron المعزولة بوصفها [مهام في الخلفية](/automation/tasks). +```json5 +{ + cron: { + failureDestination: { + mode: "announce", + channel: "last", + to: "channel:C1234567890", + accountId: "main", + }, + }, +} +``` + +- الوجهة الافتراضية لإشعارات فشل cron عبر جميع الوظائف. +- `mode`: ‏`"announce"` أو `"webhook"`؛ وتكون القيمة الافتراضية `"announce"` عندما توجد بيانات هدف كافية. +- `channel`: تجاوز القناة لتسليم announce. تؤدي `"last"` إلى إعادة استخدام آخر قناة تسليم معروفة. +- `to`: هدف announce صريح أو عنوان URL لـ webhook. وهو مطلوب لوضع webhook. +- `accountId`: تجاوز اختياري للحساب عند التسليم. +- يتجاوز `delivery.failureDestination` لكل وظيفة هذا الافتراضي العام. +- عندما لا تكون الوجهة العامة ولا الوجهة الخاصة بكل وظيفة مضبوطة، فإن الوظائف التي تسلّم بالفعل عبر `announce` تعود عند الفشل إلى هدف announce الأساسي نفسه. +- لا تكون `delivery.failureDestination` مدعومة إلا للوظائف ذات `sessionTarget="isolated"` ما لم يكن `delivery.mode` الأساسي للوظيفة هو `"webhook"`. + +راجع [وظائف Cron](/ar/automation/cron-jobs). ويتم تتبع تشغيلات cron المعزولة كـ [مهام خلفية](/ar/automation/tasks). --- ## متغيرات قالب نموذج الوسائط -العناصر النائبة للقوالب الموسعة في `tools.media.models[].args`: +عناصر نائبة للقوالب يتم توسيعها في `tools.media.models[].args`: -| المتغير | الوصف | -| ------- | ----- | -| `{{Body}}` | النص الكامل للرسالة الواردة | +| المتغير | الوصف | +| ------------------ | ------------------------------------------------- | +| `{{Body}}` | نص الرسالة الواردة الكامل | | `{{RawBody}}` | النص الخام (من دون أغلفة السجل/المرسل) | -| `{{BodyStripped}}` | النص بعد إزالة إشارات المجموعة | +| `{{BodyStripped}}` | النص بعد إزالة إشارات المجموعات | | `{{From}}` | معرّف المرسل | | `{{To}}` | معرّف الوجهة | | `{{MessageSid}}` | معرّف رسالة القناة | @@ -2797,29 +3711,40 @@ __OC_I18N_900102__ | `{{MediaType}}` | نوع الوسائط (صورة/صوت/مستند/…) | | `{{Transcript}}` | النص المفرغ للصوت | | `{{Prompt}}` | media prompt المحلول لإدخالات CLI | -| `{{MaxChars}}` | الحد الأقصى المحلول لأحرف الخرج لإدخالات CLI | +| `{{MaxChars}}` | الحد الأقصى المحلول لأحرف الإخراج لإدخالات CLI | | `{{ChatType}}` | `"direct"` أو `"group"` | | `{{GroupSubject}}` | موضوع المجموعة (بأفضل جهد) | | `{{GroupMembers}}` | معاينة أعضاء المجموعة (بأفضل جهد) | -| `{{SenderName}}` | اسم العرض للمرسل (بأفضل جهد) | +| `{{SenderName}}` | الاسم المعروض للمرسل (بأفضل جهد) | | `{{SenderE164}}` | رقم هاتف المرسل (بأفضل جهد) | -| `{{Provider}}` | تلميح الموفر (whatsapp أو telegram أو discord، إلخ) | +| `{{Provider}}` | تلميح الموفّر (whatsapp أو telegram أو discord وما إلى ذلك) | --- -## تضمين الإعدادات (`$include`) +## تضمينات الإعدادات (`$include`) قسّم الإعدادات إلى عدة ملفات: -__OC_I18N_900103__ + +```json5 +// ~/.openclaw/openclaw.json +{ + gateway: { port: 18789 }, + agents: { $include: "./agents.json5" }, + broadcast: { + $include: ["./clients/mueller.json5", "./clients/schmidt.json5"], + }, +} +``` + **سلوك الدمج:** - ملف واحد: يستبدل الكائن الحاوي. -- مصفوفة ملفات: تُدمج بعمق بالترتيب (واللاحق يتجاوز السابق). -- المفاتيح الشقيقة: تُدمج بعد التضمينات (وتتجاوز القيم المضمّنة). -- التضمينات المتداخلة: حتى 10 مستويات عمق. -- المسارات: تُحل نسبةً إلى الملف الذي يتضمنها، لكن يجب أن تبقى داخل دليل الإعدادات ذي المستوى الأعلى (`dirname` لـ `openclaw.json`). ويُسمح بالأشكال المطلقة/`../` فقط عندما تُحل مع ذلك داخل هذا الحد. +- مصفوفة ملفات: يتم دمجها عميقاً بالترتيب (حيث تتجاوز القيم اللاحقة القيم السابقة). +- المفاتيح المجاورة: تُدمج بعد التضمينات (وتتجاوز القيم المضمنة). +- التضمينات المتداخلة: حتى عمق 10 مستويات. +- المسارات: يتم حلها بالنسبة إلى الملف المُضمِّن، لكن يجب أن تبقى داخل دليل الإعدادات الأعلى مستوى (`dirname` الخاص بـ `openclaw.json`). وتُسمح الصيغ المطلقة/`../` فقط عندما تُحل داخل ذلك الحد. - الأخطاء: رسائل واضحة للملفات المفقودة، وأخطاء التحليل، والتضمينات الدائرية. --- -_ذو صلة: [الإعدادات](/ar/gateway/configuration) · [أمثلة الإعدادات](/ar/gateway/configuration-examples) · [Doctor](/ar/gateway/doctor)_ +_ذو صلة: [الإعدادات](/ar/gateway/configuration) · [أمثلة على الإعدادات](/ar/gateway/configuration-examples) · [Doctor](/ar/gateway/doctor)_ diff --git a/docs/ar/help/gpt54-codex-agentic-parity-maintainers.md b/docs/ar/help/gpt54-codex-agentic-parity-maintainers.md new file mode 100644 index 000000000..f5c1d961a --- /dev/null +++ b/docs/ar/help/gpt54-codex-agentic-parity-maintainers.md @@ -0,0 +1,174 @@ +--- +x-i18n: + generated_at: "2026-04-11T15:15:51Z" + model: gpt-5.4 + provider: openai + source_hash: 910bcf7668becf182ef48185b43728bf2fa69629d6d50189d47d47b06f807a9e + source_path: help/gpt54-codex-agentic-parity-maintainers.md + workflow: 15 +--- + +# ملاحظات الصيانة لتكافؤ GPT-5.4 / Codex + +تشرح هذه الملاحظة كيفية مراجعة برنامج تكافؤ GPT-5.4 / Codex بوصفه أربع وحدات دمج، من دون فقدان البنية الأصلية ذات العقود الستة. + +## وحدات الدمج + +### طلب السحب A: التنفيذ الصارم القائم على الوكلاء + +يشمل: + +- `executionContract` +- المتابعة في نفس الدور مع إعطاء الأولوية لـ GPT-5 +- `update_plan` كتتبّع غير نهائي للتقدم +- حالات التعذر الصريحة بدلًا من التوقفات الصامتة المعتمدة على الخطة فقط + +لا يشمل: + +- تصنيف فشل المصادقة/بيئة التشغيل +- الصدق في الأذونات +- إعادة تصميم إعادة التشغيل/الاستئناف +- قياس التكافؤ + +### طلب السحب B: الصدق في بيئة التشغيل + +يشمل: + +- صحة نطاق Codex OAuth +- التصنيف المطبوع لفشل المزوّد/بيئة التشغيل +- الصدق في إتاحة `/elevated full` وأسباب التعذر + +لا يشمل: + +- توحيد مخطط الأدوات +- حالة إعادة التشغيل/الحيوية +- بوابة القياس + +### طلب السحب C: صحة التنفيذ + +يشمل: + +- توافق الأدوات المملوكة للمزوّد مع OpenAI/Codex +- التعامل الصارم مع المخطط الخالي من المعلمات +- إظهار حالات إعادة التشغيل غير الصالحة +- إظهار حالة المهام الطويلة عند التوقف المؤقت أو التعذر أو الهجر + +لا يشمل: + +- الاستئناف الذي يقرره النظام ذاتيًا +- سلوك لهجة Codex العامة خارج خطافات المزوّد +- بوابة القياس + +### طلب السحب D: أداة اختبار التكافؤ + +يشمل: + +- الحزمة الأولى من السيناريوهات لـ GPT-5.4 مقابل Opus 4.6 +- توثيق التكافؤ +- تقرير التكافؤ وآليات بوابة الإصدار + +لا يشمل: + +- تغييرات سلوك بيئة التشغيل خارج QA-lab +- محاكاة المصادقة/الوكيل/DNS داخل أداة الاختبار + +## الربط بالعقود الستة الأصلية + +| العقد الأصلي | وحدة الدمج | +| ----------------------------------------- | ---------- | +| صحة النقل/المصادقة لدى المزوّد | طلب السحب B | +| توافق عقد الأداة/المخطط | طلب السحب C | +| التنفيذ في نفس الدور | طلب السحب A | +| الصدق في الأذونات | طلب السحب B | +| صحة إعادة التشغيل/الاستئناف/الحيوية | طلب السحب C | +| بوابة القياس/الإصدار | طلب السحب D | + +## ترتيب المراجعة + +1. طلب السحب A +2. طلب السحب B +3. طلب السحب C +4. طلب السحب D + +طلب السحب D هو طبقة الإثبات. يجب ألا يكون سببًا في تأخير طلبات السحب الخاصة بصحة بيئة التشغيل. + +## ما الذي يجب البحث عنه + +### طلب السحب A + +- تشغيلات GPT-5 تنفذ أو تفشل بشكل مغلق بدلًا من التوقف عند التعليق +- لم يعد `update_plan` يبدو وكأنه تقدم بحد ذاته +- يظل السلوك مع إعطاء الأولوية لـ GPT-5 وضمن نطاق embedded-Pi + +### طلب السحب B + +- لم تعد حالات فشل المصادقة/الوكيل/بيئة التشغيل تنهار في معالجة عامة من نوع "فشل النموذج" +- لا يتم وصف `/elevated full` بأنه متاح إلا عندما يكون متاحًا فعلًا +- تكون أسباب التعذر مرئية لكل من النموذج وبيئة التشغيل المواجهة للمستخدم + +### طلب السحب C + +- يعمل تسجيل الأدوات الصارم في OpenAI/Codex بطريقة متوقعة +- لا تفشل الأدوات الخالية من المعلمات في فحوصات المخطط الصارمة +- تحافظ نتائج إعادة التشغيل والضغط على حالة حيوية صادقة + +### طلب السحب D + +- تكون حزمة السيناريوهات مفهومة وقابلة لإعادة الإنتاج +- تتضمن الحزمة مسار أمان إعادة تشغيل متحوّل، وليس تدفقات للقراءة فقط +- تكون التقارير قابلة للقراءة من قبل البشر والأتمتة +- تكون ادعاءات التكافؤ مدعومة بالأدلة وليست قصصية + +المخرجات المتوقعة من طلب السحب D: + +- `qa-suite-report.md` / `qa-suite-summary.json` لكل تشغيل نموذج +- `qa-agentic-parity-report.md` مع مقارنة مجمعة وعلى مستوى السيناريو +- `qa-agentic-parity-summary.json` مع قرار مقروء آليًا + +## بوابة الإصدار + +لا تدّعِ وجود تكافؤ أو تفوق لـ GPT-5.4 على Opus 4.6 حتى: + +- يتم دمج طلبات السحب A وB وC +- يشغّل طلب السحب D حزمة التكافؤ الأولى بنجاح كامل +- تظل مجموعات انحدار الصدق في بيئة التشغيل خضراء +- يُظهر تقرير التكافؤ عدم وجود حالات نجاح زائف وعدم وجود تراجع في سلوك التوقف + +```mermaid +flowchart LR + A["PR A-C merged"] --> B["Run GPT-5.4 parity pack"] + A --> C["Run Opus 4.6 parity pack"] + B --> D["qa-suite-summary.json"] + C --> E["qa-suite-summary.json"] + D --> F["qa parity-report"] + E --> F + F --> G["Markdown report + JSON verdict"] + G --> H{"Pass?"} + H -- "yes" --> I["Parity claim allowed"] + H -- "no" --> J["Keep runtime fixes / review loop open"] +``` + +أداة اختبار التكافؤ ليست مصدر الأدلة الوحيد. أبقِ هذا الفصل واضحًا في المراجعة: + +- يملك طلب السحب D المقارنة القائمة على السيناريو بين GPT-5.4 وOpus 4.6 +- وما تزال المجموعات الحتمية في طلب السحب B هي المالكة لأدلة المصادقة/الوكيل/DNS وصدق الوصول الكامل + +## خريطة الهدف إلى الدليل + +| عنصر بوابة الإكمال | المالك الأساسي | مخرج المراجعة | +| ---------------------------------------- | -------------- | ------------------------------------------------------------------- | +| عدم وجود توقفات تعتمد على الخطة فقط | طلب السحب A | اختبارات بيئة التشغيل الصارمة القائمة على الوكلاء و`approval-turn-tool-followthrough` | +| عدم وجود تقدم زائف أو إتمام أداة زائف | طلب السحب A + D | عدد حالات النجاح الزائف في التكافؤ مع تفاصيل التقرير على مستوى السيناريو | +| عدم وجود إرشادات خاطئة حول `/elevated full` | طلب السحب B | مجموعات الصدق الحتمية في بيئة التشغيل | +| بقاء إخفاقات إعادة التشغيل/الحيوية صريحة | طلب السحب C + D | مجموعات lifecycle/replay بالإضافة إلى `compaction-retry-mutating-tool` | +| أن يطابق GPT-5.4 أو يتفوق على Opus 4.6 | طلب السحب D | `qa-agentic-parity-report.md` و`qa-agentic-parity-summary.json` | + +## صياغة مختصرة للمراجع: قبل مقابل بعد + +| المشكلة المرئية للمستخدم سابقًا | إشارة المراجعة لاحقًا | +| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------ | +| كان GPT-5.4 يتوقف بعد التخطيط | يُظهر طلب السحب A سلوكًا ينفذ أو يتعذر بدلًا من الاكتمال القائم على التعليق فقط | +| بدا استخدام الأدوات هشًا مع مخططات OpenAI/Codex الصارمة | يحافظ طلب السحب C على إمكانية التنبؤ بتسجيل الأدوات واستدعائها من دون معلمات | +| كانت تلميحات `/elevated full` مضللة أحيانًا | يربط طلب السحب B الإرشاد بقدرة بيئة التشغيل الفعلية وأسباب التعذر | +| كان يمكن أن تختفي المهام الطويلة داخل غموض إعادة التشغيل/الضغط | يُصدر طلب السحب C حالات صريحة للتوقف المؤقت والتعذر والهجر وإعادة التشغيل غير الصالحة | +| كانت ادعاءات التكافؤ قصصية | يُنتج طلب السحب D تقريرًا بالإضافة إلى قرار JSON مع التغطية نفسها للسيناريوهات على كلا النموذجين | diff --git a/docs/ar/help/gpt54-codex-agentic-parity.md b/docs/ar/help/gpt54-codex-agentic-parity.md new file mode 100644 index 000000000..9fe05a7d9 --- /dev/null +++ b/docs/ar/help/gpt54-codex-agentic-parity.md @@ -0,0 +1,229 @@ +--- +x-i18n: + generated_at: "2026-04-11T15:15:51Z" + model: gpt-5.4 + provider: openai + source_hash: 7ee6b925b8a0f8843693cea9d50b40544657b5fb8a9e0860e2ff5badb273acb6 + source_path: help/gpt54-codex-agentic-parity.md + workflow: 15 +--- + +# التكافؤ الوكيلي بين GPT-5.4 / Codex في OpenClaw + +كان OpenClaw يعمل بالفعل بشكل جيد مع النماذج الرائدة التي تستخدم الأدوات، لكن نماذج GPT-5.4 وCodex-style كانت لا تزال أقل أداءً في بعض الجوانب العملية: + +- كان يمكنها التوقف بعد التخطيط بدلًا من تنفيذ العمل +- كان يمكنها استخدام مخططات أدوات OpenAI/Codex الصارمة بشكل غير صحيح +- كان يمكنها طلب `/elevated full` حتى عندما يكون الوصول الكامل مستحيلًا +- كان يمكنها فقدان حالة المهام طويلة التشغيل أثناء إعادة التشغيل أو الضغط +- كانت ادعاءات التكافؤ مقارنةً بـ Claude Opus 4.6 تستند إلى روايات فردية بدلًا من سيناريوهات قابلة للتكرار + +يعالج برنامج التكافؤ هذا هذه الفجوات عبر أربع شرائح قابلة للمراجعة. + +## ما الذي تغيّر + +### طلب السحب A: تنفيذ strict-agentic + +تضيف هذه الشريحة عقد تنفيذ `strict-agentic` اختياريًا لتشغيلات Pi GPT-5 المضمّنة. + +عند تفعيله، يتوقف OpenClaw عن قبول الأدوار التي تحتوي على خطة فقط باعتبارها إكمالًا “جيدًا بما يكفي”. إذا اكتفى النموذج بقول ما ينوي فعله ولم يستخدم الأدوات فعليًا أو يحرز تقدمًا، يعيد OpenClaw المحاولة بتوجيه ينص على التنفيذ الفوري، ثم يفشل بشكل مغلق مع حالة تعطّل صريحة بدلًا من إنهاء المهمة بصمت. + +ويحسّن ذلك تجربة GPT-5.4 بشكل خاص في الحالات التالية: + +- المتابعات القصيرة مثل “حسنًا افعل ذلك” +- مهام البرمجة حيث تكون الخطوة الأولى واضحة +- التدفقات التي يجب أن يكون فيها `update_plan` لتتبع التقدم بدلًا من كونه نصًا حشوًا + +### طلب السحب B: صدق وقت التشغيل + +تجعل هذه الشريحة OpenClaw يقول الحقيقة بشأن أمرين: + +- سبب فشل استدعاء المزوّد/وقت التشغيل +- ما إذا كان `/elevated full` متاحًا فعلًا + +وهذا يعني أن GPT-5.4 يحصل على إشارات أفضل من وقت التشغيل بشأن نقص النطاق، وإخفاقات تحديث المصادقة، وإخفاقات المصادقة عبر HTML 403، ومشكلات الوكيل، وأعطال DNS أو المهلات، وأوضاع الوصول الكامل المحجوبة. ويصبح النموذج أقل عرضة لاختلاق معالجة خاطئة أو الاستمرار في طلب وضع أذونات لا يستطيع وقت التشغيل توفيره. + +### طلب السحب C: صحة التنفيذ + +تحسّن هذه الشريحة نوعين من الصحة: + +- توافق مخططات الأدوات المملوكة للمزوّد مع OpenAI/Codex +- إظهار إعادة التشغيل وحيوية المهام الطويلة + +يقلل عمل التوافق مع الأدوات من الاحتكاك المتعلق بالمخططات عند تسجيل أدوات OpenAI/Codex الصارمة، خصوصًا حول الأدوات التي لا تحتوي على معلمات وتوقعات الجذر الصارمة من نوع object. أما عمل إعادة التشغيل/الحيوية فيجعل المهام طويلة التشغيل أكثر قابلية للملاحظة، بحيث تصبح الحالات المتوقفة مؤقتًا، والمحجوبة، والمتروكة مرئية بدلًا من أن تختفي داخل نص فشل عام. + +### طلب السحب D: حزمة التكافؤ + +تضيف هذه الشريحة أول حزمة تكافؤ من QA-lab حتى يمكن اختبار GPT-5.4 وOpus 4.6 عبر السيناريوهات نفسها ومقارنتهما باستخدام أدلة مشتركة. + +تمثل حزمة التكافؤ طبقة الإثبات. وهي لا تغيّر سلوك وقت التشغيل بحد ذاتها. + +بعد أن يصبح لديك عنصران من `qa-suite-summary.json`، أنشئ مقارنة بوابة الإصدار باستخدام: + +```bash +pnpm openclaw qa parity-report \ + --repo-root . \ + --candidate-summary .artifacts/qa-e2e/gpt54/qa-suite-summary.json \ + --baseline-summary .artifacts/qa-e2e/opus46/qa-suite-summary.json \ + --output-dir .artifacts/qa-e2e/parity +``` + +يكتب هذا الأمر ما يلي: + +- تقرير Markdown قابل للقراءة البشرية +- حكم JSON قابل للقراءة آليًا +- نتيجة بوابة صريحة `pass` / `fail` + +## لماذا يحسّن هذا GPT-5.4 عمليًا + +قبل هذا العمل، كان يمكن أن يبدو GPT-5.4 على OpenClaw أقل وكالية من Opus في جلسات البرمجة الفعلية لأن وقت التشغيل كان يتسامح مع سلوكيات تضر نماذج GPT-5-style بشكل خاص: + +- أدوار تعتمد على التعليق فقط +- احتكاك في المخططات حول الأدوات +- ملاحظات أذونات غامضة +- أعطال صامتة في إعادة التشغيل أو الضغط + +الهدف ليس جعل GPT-5.4 يقلّد Opus. بل الهدف هو منح GPT-5.4 عقد وقت تشغيل يكافئ التقدم الحقيقي، ويوفر دلالات أنظف للأدوات والأذونات، ويحوّل أوضاع الفشل إلى حالات صريحة قابلة للقراءة آليًا وبشريًا. + +وهذا يغيّر تجربة المستخدم من: + +- “كان لدى النموذج خطة جيدة لكنه توقّف” + +إلى: + +- “إما أن النموذج نفّذ، أو أن OpenClaw أظهر السبب الدقيق الذي منعه من ذلك” + +## قبل وبعد لمستخدمي GPT-5.4 + +| قبل هذا البرنامج | بعد طلبات السحب A-D | +| -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | +| كان يمكن لـ GPT-5.4 أن يتوقف بعد خطة معقولة من دون اتخاذ خطوة الأداة التالية | يحوّل طلب السحب A حالة “خطة فقط” إلى “نفّذ الآن أو أظهر حالة تعطّل محجوبة” | +| كان يمكن لمخططات الأدوات الصارمة أن ترفض الأدوات الخالية من المعلمات أو ذات شكل OpenAI/Codex بطرق مربكة | يجعل طلب السحب C تسجيل الأدوات المملوكة للمزوّد واستدعاءها أكثر قابلية للتنبؤ | +| كان يمكن أن تكون إرشادات `/elevated full` غامضة أو خاطئة في بيئات التشغيل المحجوبة | يمنح طلب السحب B كلًا من GPT-5.4 والمستخدم تلميحات صادقة عن وقت التشغيل والأذونات | +| كان يمكن أن تبدو أعطال إعادة التشغيل أو الضغط وكأن المهمة اختفت بصمت | يُظهر طلب السحب C نتائج التوقف المؤقت، والحجب، والتخلي، وبطلان إعادة التشغيل بشكل صريح | +| كانت عبارة “GPT-5.4 أسوأ من Opus” في الغالب روايات فردية | يحوّل طلب السحب D ذلك إلى حزمة السيناريوهات نفسها، والمقاييس نفسها، وبوابة نجاح/فشل صارمة | + +## البنية المعمارية + +```mermaid +flowchart TD + A["طلب المستخدم"] --> B["وقت تشغيل Pi المضمّن"] + B --> C["عقد تنفيذ strict-agentic"] + B --> D["توافق الأدوات المملوكة للمزوّد"] + B --> E["صدق وقت التشغيل"] + B --> F["إعادة التشغيل وحالة الحيوية"] + C --> G["استدعاء أداة أو حالة تعطّل محجوبة صريحة"] + D --> G + E --> G + F --> G + G --> H["حزمة تكافؤ QA-lab"] + H --> I["تقرير السيناريو وبوابة التكافؤ"] +``` + +## تدفق الإصدار + +```mermaid +flowchart LR + A["شرائح وقت التشغيل المدمجة (طلبات السحب A-C)"] --> B["تشغيل حزمة تكافؤ GPT-5.4"] + A --> C["تشغيل حزمة تكافؤ Opus 4.6"] + B --> D["qa-suite-summary.json"] + C --> E["qa-suite-summary.json"] + D --> F["openclaw qa parity-report"] + E --> F + F --> G["qa-agentic-parity-report.md"] + F --> H["qa-agentic-parity-summary.json"] + H --> I{"هل اجتازت البوابة؟"} + I -- "نعم" --> J["ادعاء تكافؤ مدعوم بالأدلة"] + I -- "لا" --> K["الإبقاء على حلقة وقت التشغيل/المراجعة مفتوحة"] +``` + +## حزمة السيناريوهات + +تغطي حزمة التكافؤ للموجة الأولى حاليًا خمسة سيناريوهات: + +### `approval-turn-tool-followthrough` + +يتحقق من أن النموذج لا يتوقف عند “سأفعل ذلك” بعد موافقة قصيرة. يجب أن يتخذ أول إجراء ملموس في الدور نفسه. + +### `model-switch-tool-continuity` + +يتحقق من أن العمل القائم على الأدوات يظل متماسكًا عبر حدود تبديل النموذج/وقت التشغيل بدلًا من أن يعاد ضبطه إلى تعليق أو أن يفقد سياق التنفيذ. + +### `source-docs-discovery-report` + +يتحقق من أن النموذج يستطيع قراءة المصدر والوثائق، وتجميع النتائج، ومواصلة المهمة بشكل وكيلي بدلًا من إنتاج ملخص سطحي والتوقف مبكرًا. + +### `image-understanding-attachment` + +يتحقق من أن المهام المختلطة التي تتضمن مرفقات تبقى قابلة للتنفيذ ولا تنهار إلى سرد غامض. + +### `compaction-retry-mutating-tool` + +يتحقق من أن مهمة تتضمن كتابة تعديلية حقيقية تُبقي عدم أمان إعادة التشغيل صريحًا بدلًا من أن تبدو آمنة لإعادة التشغيل بهدوء إذا تعرّض التشغيل للضغط أو أُعيدت المحاولة أو فُقدت حالة الرد تحت الضغط. + +## مصفوفة السيناريوهات + +| السيناريو | ما الذي يختبره | السلوك الجيد من GPT-5.4 | إشارة الفشل | +| ----------------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- | +| `approval-turn-tool-followthrough` | أدوار الموافقة القصيرة بعد خطة | يبدأ أول إجراء أداة ملموس فورًا بدلًا من إعادة صياغة النية | متابعة بخطة فقط، أو دون نشاط أدوات، أو دور محجوب دون مانع حقيقي | +| `model-switch-tool-continuity` | تبديل وقت التشغيل/النموذج أثناء استخدام الأدوات | يحافظ على سياق المهمة ويواصل التنفيذ بشكل متماسك | يعاد ضبطه إلى تعليق، أو يفقد سياق الأدوات، أو يتوقف بعد التبديل | +| `source-docs-discovery-report` | قراءة المصدر + التجميع + الإجراء | يعثر على المصادر، ويستخدم الأدوات، وينتج تقريرًا مفيدًا دون تعثر | ملخص سطحي، أو غياب عمل الأدوات، أو توقف في دور غير مكتمل | +| `image-understanding-attachment` | عمل وكيلي مدفوع بالمرفقات | يفسر المرفق، ويربطه بالأدوات، ويواصل المهمة | سرد غامض، أو تجاهل المرفق، أو عدم وجود إجراء تالٍ ملموس | +| `compaction-retry-mutating-tool` | عمل تعديلي تحت ضغط الضغط | ينفذ كتابة حقيقية ويُبقي عدم أمان إعادة التشغيل صريحًا بعد الأثر الجانبي | تحدث كتابة تعديل، لكن يُفهم ضمنًا أن إعادة التشغيل آمنة، أو يكون ذلك مفقودًا أو متناقضًا | + +## بوابة الإصدار + +لا يمكن اعتبار GPT-5.4 عند مستوى التكافؤ أو أفضل إلا عندما يجتاز وقت التشغيل المدمج حزمة التكافؤ وانحدارات صدق وقت التشغيل في الوقت نفسه. + +النتائج المطلوبة: + +- عدم وجود تعثر عند خطة فقط عندما يكون إجراء الأداة التالي واضحًا +- عدم وجود إكمال مزيف من دون تنفيذ حقيقي +- عدم وجود إرشادات خاطئة بشأن `/elevated full` +- عدم وجود تخلٍ صامت عن إعادة التشغيل أو الضغط +- مقاييس حزمة التكافؤ تكون على الأقل بقوة خط الأساس المتفق عليه لـ Opus 4.6 + +بالنسبة إلى حزمة الموجة الأولى، تقارن البوابة ما يلي: + +- معدل الإكمال +- معدل التوقف غير المقصود +- معدل استدعاء الأدوات الصحيح +- عدد النجاحات المزيفة + +ينقسم دليل التكافؤ عمدًا إلى طبقتين: + +- يثبت طلب السحب D سلوك GPT-5.4 مقابل Opus 4.6 في السيناريوهات نفسها باستخدام QA-lab +- وتثبت المجموعات الحتمية في طلب السحب B صدق المصادقة والوكيل وDNS و`/elevated full` خارج الحزمة + +## مصفوفة الهدف إلى الدليل + +| عنصر بوابة الإكمال | طلب السحب المالك | مصدر الدليل | إشارة النجاح | +| ------------------------------------------------------ | ---------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------- | +| لم يعد GPT-5.4 يتعثر بعد التخطيط | PR A | `approval-turn-tool-followthrough` بالإضافة إلى مجموعات وقت تشغيل PR A | تؤدي أدوار الموافقة إلى عمل حقيقي أو إلى حالة تعطّل محجوبة صريحة | +| لم يعد GPT-5.4 يزيف التقدم أو إكمال الأداة المزيف | PR A + PR D | نتائج سيناريوهات تقرير التكافؤ وعدد النجاحات المزيفة | عدم وجود نتائج نجاح مشبوهة وعدم وجود إكمال قائم على التعليق فقط | +| لم يعد GPT-5.4 يعطي إرشادات `/elevated full` خاطئة | PR B | مجموعات الصدق الحتمية | تبقى أسباب الحجب وتلميحات الوصول الكامل دقيقة وفق وقت التشغيل | +| تبقى أعطال إعادة التشغيل/الحيوية صريحة | PR C + PR D | مجموعات دورة الحياة/إعادة التشغيل في PR C بالإضافة إلى `compaction-retry-mutating-tool` | يُبقي العمل التعديلي عدم أمان إعادة التشغيل صريحًا بدلًا من أن يختفي بصمت | +| يطابق GPT-5.4 أو يتفوق على Opus 4.6 في المقاييس المتفق عليها | PR D | `qa-agentic-parity-report.md` و`qa-agentic-parity-summary.json` | التغطية نفسها للسيناريوهات وعدم وجود تراجع في الإكمال أو سلوك التوقف أو صحة استخدام الأدوات | + +## كيفية قراءة حكم التكافؤ + +استخدم الحكم الموجود في `qa-agentic-parity-summary.json` باعتباره القرار النهائي القابل للقراءة آليًا لحزمة التكافؤ الخاصة بالموجة الأولى. + +- تعني `pass` أن GPT-5.4 غطّى السيناريوهات نفسها التي غطاها Opus 4.6 ولم يتراجع في المقاييس التجميعية المتفق عليها. +- تعني `fail` أن بوابة صارمة واحدة على الأقل قد تعثرت: إكمال أضعف، أو توقفات غير مقصودة أسوأ، أو استخدام صحيح أضعف للأدوات، أو أي حالة نجاح مزيف، أو تغطية سيناريوهات غير متطابقة. +- لا تُعد “مشكلة CI مشتركة/أساسية” بحد ذاتها نتيجة تكافؤ. إذا كان ضجيج CI خارج PR D يحجب تشغيلًا ما، فيجب أن ينتظر الحكم تنفيذًا نظيفًا لوقت تشغيل مدمج بدلًا من استنتاجه من سجلات مرحلة الفرع. +- لا تزال دقة المصادقة والوكيل وDNS و`/elevated full` تأتي من المجموعات الحتمية في PR B، لذلك يحتاج ادعاء الإصدار النهائي إلى الأمرين معًا: حكم تكافؤ ناجح من PR D وتغطية صدق خضراء من PR B. + +## من الذي ينبغي له تفعيل `strict-agentic` + +استخدم `strict-agentic` عندما: + +- يُتوقع من الوكيل أن يتصرف فورًا عندما تكون الخطوة التالية واضحة +- تكون نماذج GPT-5.4 أو نماذج Codex-family هي وقت التشغيل الأساسي +- تفضّل الحالات المحجوبة الصريحة على الردود التي تقتصر على التلخيص “المفيد” + +أبقِ العقد الافتراضي عندما: + +- تريد السلوك الأرخى الحالي +- لا تستخدم نماذج GPT-5-family +- تختبر المطالبات بدلًا من فرض وقت التشغيل diff --git a/docs/ar/plugins/architecture.md b/docs/ar/plugins/architecture.md index cd53e6631..a9a24f392 100644 --- a/docs/ar/plugins/architecture.md +++ b/docs/ar/plugins/architecture.md @@ -1,187 +1,190 @@ --- read_when: - - عند بناء إضافات OpenClaw الأصلية أو تصحيح أخطائها - - عند فهم نموذج قدرات الإضافة أو حدود الملكية - - عند العمل على مسار تحميل الإضافة أو السجل - - عند تنفيذ خطافات وقت تشغيل المزود أو إضافات القنوات + - بناء إضافات OpenClaw الأصلية أو تصحيح أخطائها + - فهم نموذج إمكانات الإضافة أو حدود الملكية + - العمل على مسار تحميل الإضافات أو السجل + - تنفيذ خطافات وقت تشغيل المزوّد أو إضافات القنوات sidebarTitle: Internals -summary: 'الأجزاء الداخلية للإضافة: نموذج القدرات، والملكية، والعقود، ومسار التحميل، ومساعدات وقت التشغيل' -title: الأجزاء الداخلية للإضافات +summary: 'الواجهات الداخلية للإضافات: نموذج الإمكانات، والملكية، والعقود، ومسار التحميل، ومساعدات وقت التشغيل' +title: الواجهات الداخلية للإضافات x-i18n: - generated_at: "2026-04-09T01:32:47Z" + generated_at: "2026-04-11T15:16:01Z" model: gpt-5.4 provider: openai - source_hash: 2575791f835990589219bb06d8ca92e16a8c38b317f0bfe50b421682f253ef18 + source_hash: 7cac67984d0d729c0905bcf5c18372fb0d9b02bbd3a531580b7e2ef483ef40a6 source_path: plugins/architecture.md workflow: 15 --- -# الأجزاء الداخلية للإضافات +# الواجهات الداخلية للإضافات هذا هو **مرجع البنية العميقة**. للاطلاع على الأدلة العملية، راجع: - [تثبيت الإضافات واستخدامها](/ar/tools/plugin) — دليل المستخدم - - [البدء](/ar/plugins/building-plugins) — أول درس تعليمي للإضافات - - [إضافات القنوات](/ar/plugins/sdk-channel-plugins) — بناء قناة مراسلة - - [إضافات المزود](/ar/plugins/sdk-provider-plugins) — بناء مزود نماذج - - [نظرة عامة على SDK](/ar/plugins/sdk-overview) — خريطة الاستيراد وواجهة برمجة التسجيل + - [البدء](/ar/plugins/building-plugins) — أول درس تعليمي للإضافة + - [إضافات القنوات](/ar/plugins/sdk-channel-plugins) — أنشئ قناة مراسلة + - [إضافات المزوّدين](/ar/plugins/sdk-provider-plugins) — أنشئ مزوّد نماذج + - [نظرة عامة على SDK](/ar/plugins/sdk-overview) — خريطة الاستيراد وواجهة API للتسجيل -تغطي هذه الصفحة البنية الداخلية لنظام الإضافات في OpenClaw. +تغطي هذه الصفحة البنية الداخلية لنظام إضافات OpenClaw. -## نموذج القدرات العام +## نموذج الإمكانات العام -القدرات هي نموذج **الإضافات الأصلية** العام داخل OpenClaw. كل -إضافة OpenClaw أصلية تسجل نفسها مقابل نوع قدرة واحد أو أكثر: +الإمكانات هي نموذج **الإضافات الأصلية** العام داخل OpenClaw. تسجّل كل +إضافة OpenClaw أصلية في نوع واحد أو أكثر من أنواع الإمكانات: -| القدرة | طريقة التسجيل | أمثلة على الإضافات | -| ---------------------- | ------------------------------------------------ | ------------------------------------ | -| استدلال النص | `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` | -الإضافة التي تسجل صفرًا من القدرات لكنها توفر خطافات أو أدوات أو +الإضافة التي تسجّل صفرًا من الإمكانات لكنها توفّر خطافات أو أدوات أو خدمات هي إضافة **قديمة تعتمد على الخطافات فقط**. لا يزال هذا النمط مدعومًا بالكامل. ### موقف التوافق الخارجي -تم اعتماد نموذج القدرات في النواة ويُستخدم اليوم من قبل الإضافات -المجمعة/الأصلية، لكن توافق الإضافات الخارجية لا يزال يحتاج إلى معيار -أشد من مجرد "تم تصديره، إذن فهو ثابت". +تم اعتماد نموذج الإمكانات في النواة ويُستخدم اليوم بواسطة الإضافات +المضمّنة/الأصلية، لكن توافق الإضافات الخارجية لا يزال يحتاج إلى معيار +أكثر صرامة من "تم تصديره، إذًا هو ثابت." الإرشادات الحالية: -- **الإضافات الخارجية الحالية:** حافظ على عمل التكاملات المعتمدة على الخطافات؛ واعتبر - هذا خط الأساس للتوافق -- **الإضافات الجديدة المجمعة/الأصلية:** فضّل تسجيل القدرات الصريح بدلًا من - التوغل الخاص بالمورد أو التصميمات الجديدة المعتمدة على الخطافات فقط -- **الإضافات الخارجية التي تتبنى تسجيل القدرات:** هذا مسموح، لكن تعامل مع - الأسطح المساعدة الخاصة بالقدرات على أنها تتطور ما لم توضح الوثائق - صراحةً أن العقد مستقر +- **الإضافات الخارجية الحالية:** حافظ على عمل التكاملات المعتمدة على + الخطافات؛ واعتبر ذلك خط الأساس للتوافق +- **الإضافات المضمّنة/الأصلية الجديدة:** فضّل تسجيل الإمكانات الصريح بدلًا + من الوصولات الخاصة بالمورّد أو التصاميم الجديدة المعتمدة على الخطافات فقط +- **الإضافات الخارجية التي تعتمد تسجيل الإمكانات:** هذا مسموح، لكن اعتبر + أسطح المساعدة الخاصة بالإمكانات قيد التطور ما لم تذكر الوثائق صراحة أن + العقد ثابت القاعدة العملية: -- واجهات تسجيل القدرات هي الاتجاه المقصود -- تظل الخطافات القديمة المسار الأكثر أمانًا لتجنب الكسر للإضافات الخارجية خلال +- واجهات API لتسجيل الإمكانات هي الاتجاه المقصود +- تظل الخطافات القديمة المسار الأكثر أمانًا لعدم كسر الإضافات الخارجية خلال مرحلة الانتقال -- ليست كل المسارات الفرعية المساعدة المصدّرة متساوية؛ فضّل العقد الضيق الموثّق، - لا الصادرات المساعدة العرضية +- ليست كل المسارات الفرعية المصدّرة متساوية؛ فضّل العقد الضيق الموثّق، لا + صادرات المساعدة العرضية ### أشكال الإضافات -يصنف OpenClaw كل إضافة محملة إلى شكل بناءً على سلوك التسجيل الفعلي الخاص بها +يصنّف OpenClaw كل إضافة محمّلة إلى شكل اعتمادًا على سلوك تسجيلها الفعلي (وليس فقط على البيانات الوصفية الثابتة): -- **plain-capability** -- يسجل نوع قدرة واحدًا فقط (مثل - إضافة مزود فقط مثل `mistral`) -- **hybrid-capability** -- يسجل عدة أنواع من القدرات (مثل - `openai` الذي يملك استدلال النص والكلام وفهم الوسائط وتوليد - الصور) -- **hook-only** -- يسجل خطافات فقط (مكتوبة الأنواع أو مخصصة)، من دون قدرات - أو أدوات أو أوامر أو خدمات -- **non-capability** -- يسجل أدوات أو أوامر أو خدمات أو مسارات، ولكن من دون - قدرات +- **plain-capability** -- تسجّل نوع إمكانية واحدًا فقط (على سبيل المثال + إضافة مزوّد فقط مثل `mistral`) +- **hybrid-capability** -- تسجّل عدة أنواع من الإمكانات (على سبيل المثال + `openai` يملك استدلال النص والكلام وفهم الوسائط وتوليد الصور) +- **hook-only** -- تسجّل الخطافات فقط (المكتوبة Typed أو المخصّصة)، بدون + إمكانات أو أدوات أو أوامر أو خدمات +- **non-capability** -- تسجّل أدوات أو أوامر أو خدمات أو مسارات، لكن بدون + إمكانات -استخدم `openclaw plugins inspect ` لرؤية شكل الإضافة وتفصيل -القدرات الخاصة بها. راجع [مرجع CLI](/cli/plugins#inspect) للتفاصيل. +استخدم `openclaw plugins inspect ` لرؤية شكل الإضافة وتفصيل إمكاناتها. +راجع [مرجع CLI](/cli/plugins#inspect) لمزيد من التفاصيل. ### الخطافات القديمة -لا يزال الخطاف `before_agent_start` مدعومًا كمسار توافق للإضافات -المعتمدة على الخطافات فقط. لا تزال الإضافات القديمة المستخدمة فعليًا تعتمد عليه. +لا يزال الخطاف `before_agent_start` مدعومًا كمسار توافق للإضافات المعتمدة +على الخطافات فقط. لا تزال إضافات قديمة مستخدمة فعليًا تعتمد عليه. الاتجاه: -- الاستمرار في دعمه -- توثيقه على أنه قديم -- تفضيل `before_model_resolve` لأعمال تجاوز النموذج/المزود -- تفضيل `before_prompt_build` لأعمال تعديل الموجّه -- عدم إزالته إلا بعد انخفاض الاستخدام الفعلي وإثبات أمان الترحيل عبر تغطية التركيبات الاختبارية +- أبقه يعمل +- وثّقه بوصفه قديمًا +- فضّل `before_model_resolve` لعمليات تجاوز النموذج/المزوّد +- فضّل `before_prompt_build` لعمليات تعديل المطالبة +- أزله فقط بعد انخفاض الاستخدام الفعلي وعندما يثبت تغطية الاختبارات أمان + الترحيل ### إشارات التوافق -عند تشغيل `openclaw doctor` أو `openclaw plugins inspect `, قد ترى +عند تشغيل `openclaw doctor` أو `openclaw plugins inspect `، قد ترى إحدى هذه التسميات: -| الإشارة | المعنى | +| الإشارة | المعنى | | -------------------------- | ------------------------------------------------------------ | -| **config valid** | يتم تحليل الإعدادات بشكل صحيح ويتم حل الإضافات | -| **compatibility advisory** | تستخدم الإضافة نمطًا مدعومًا ولكنه أقدم (مثل `hook-only`) | -| **legacy warning** | تستخدم الإضافة `before_agent_start`، وهو مهمل | -| **hard error** | الإعدادات غير صالحة أو فشل تحميل الإضافة | +| **config valid** | يجري تحليل الإعدادات بشكل صحيح وتُحل الإضافات | +| **compatibility advisory** | تستخدم الإضافة نمطًا مدعومًا لكنه أقدم (مثل `hook-only`) | +| **legacy warning** | تستخدم الإضافة `before_agent_start`، وهو مهمل | +| **hard error** | الإعدادات غير صالحة أو فشل تحميل الإضافة | -لن يؤدي `hook-only` ولا `before_agent_start` إلى كسر إضافتك اليوم -- -فـ `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`. ## نظرة عامة على البنية -يتكون نظام الإضافات في OpenClaw من أربع طبقات: +يتكوّن نظام الإضافات في OpenClaw من أربع طبقات: 1. **البيان + الاكتشاف** - يعثر OpenClaw على الإضافات المرشحة من المسارات المهيأة وجذور مساحة العمل - والجذور العامة للإضافات والامتدادات المجمعة. يقرأ الاكتشاف بيانات - `openclaw.plugin.json` الأصلية بالإضافة إلى بيانات الحزم المدعومة أولًا. + يعثر OpenClaw على الإضافات المرشحة من المسارات المهيأة، وجذور مساحات + العمل، وجذور الامتدادات العامة، والامتدادات المضمّنة. يقرأ الاكتشاف + بيانات `openclaw.plugin.json` الخاصة بالإضافات الأصلية بالإضافة إلى + بيانات الحِزم المدعومة أولًا. 2. **التمكين + التحقق** - تقرر النواة ما إذا كانت الإضافة المكتشفة مُمكّنة أو معطلة أو محظورة أو - محددة لفتحة حصرية مثل الذاكرة. -3. **التحميل وقت التشغيل** - تُحمَّل إضافات OpenClaw الأصلية داخل العملية عبر jiti وتُسجَّل - القدرات في سجل مركزي. وتُطبَّع الحزم المتوافقة إلى سجلات في - السجل من دون استيراد شيفرة وقت التشغيل. + تحدد النواة ما إذا كانت الإضافة المكتشفة ممكّنة أو معطّلة أو محظورة أو + محددة لخانة حصرية مثل الذاكرة. +3. **التحميل في وقت التشغيل** + تُحمَّل إضافات OpenClaw الأصلية داخل العملية عبر jiti وتُسجّل الإمكانات + في سجل مركزي. وتُطبَّع الحِزم المتوافقة إلى سجلات في السجل بدون استيراد + شيفرة وقت التشغيل. 4. **استهلاك الأسطح** - يقرأ باقي OpenClaw السجل لإظهار الأدوات والقنوات وإعداد المزود - والخطافات ومسارات HTTP وأوامر CLI والخدمات. + يقرأ بقية OpenClaw السجل لكشف الأدوات، والقنوات، وإعداد المزوّدين، + والخطافات، ومسارات HTTP، وأوامر CLI، والخدمات. -وبالنسبة إلى CLI الخاص بالإضافات تحديدًا، يُقسَّم اكتشاف الأمر الجذر إلى مرحلتين: +وبالنسبة إلى CLI الخاص بالإضافات تحديدًا، ينقسم اكتشاف أوامر الجذر إلى +مرحلتين: -- تأتي بيانات التحليل الوصفية من `registerCli(..., { descriptors: [...] })` +- تأتي البيانات الوصفية في وقت التحليل من `registerCli(..., { descriptors: [...] })` - يمكن أن تبقى وحدة CLI الحقيقية الخاصة بالإضافة كسولة وتُسجَّل عند أول استدعاء -هذا يبقي شيفرة CLI المملوكة للإضافة داخل الإضافة مع السماح لـ OpenClaw في -الوقت نفسه بحجز أسماء الأوامر الجذرية قبل التحليل. +يحافظ ذلك على شيفرة CLI المملوكة للإضافة داخل الإضافة نفسها، مع تمكين +OpenClaw من حجز أسماء أوامر الجذر قبل التحليل. -الحد التصميمي المهم: +الحدّ التصميمي المهم: -- يجب أن يعمل الاكتشاف والتحقق من الإعدادات انطلاقًا من **بيانات البيان/المخطط** - من دون تنفيذ شيفرة الإضافة +- يجب أن يعمل الاكتشاف والتحقق من الإعدادات من **بيانات البيان/المخطط + الوصفية** من دون تنفيذ شيفرة الإضافة - يأتي سلوك وقت التشغيل الأصلي من مسار `register(api)` في وحدة الإضافة -يسمح هذا الفصل لـ OpenClaw بالتحقق من الإعدادات وشرح الإضافات -المفقودة/المعطلة وبناء تلميحات الواجهة/المخطط قبل تنشيط وقت التشغيل الكامل. +يتيح هذا الفصل لـ OpenClaw التحقق من الإعدادات، وشرح الإضافات +المفقودة/المعطّلة، وبناء تلميحات واجهة المستخدم/المخطط قبل تنشيط وقت +التشغيل الكامل. ### إضافات القنوات وأداة الرسائل المشتركة -لا تحتاج إضافات القنوات إلى تسجيل أداة إرسال/تعديل/تفاعل منفصلة من أجل -إجراءات الدردشة العادية. يحتفظ OpenClaw بأداة `message` مشتركة واحدة في -النواة، بينما تملك إضافات القنوات الاكتشاف والتنفيذ الخاصين بالقناة خلفها. +لا تحتاج إضافات القنوات إلى تسجيل أداة منفصلة للإرسال/التحرير/التفاعل +لإجراءات الدردشة العادية. يحتفظ OpenClaw بأداة `message` مشتركة واحدة في +النواة، وتملك إضافات القنوات الاكتشاف والتنفيذ الخاصين بالقناة خلفها. الحد الحالي هو: -- النواة تملك مضيف أداة `message` المشتركة، وربط الموجّه، ومسك الدفاتر الخاصة - بالجلسات/المحادثات، وتوزيع التنفيذ -- إضافات القنوات تملك اكتشاف الإجراءات المقيّدة، واكتشاف القدرات، - وأي أجزاء من المخطط خاصة بالقناة -- إضافات القنوات تملك قواعد المحادثة الخاصة بالمزود للجلسة، مثل - كيفية ترميز معرفات المحادثات لمعرفات الخيوط أو وراثتها من المحادثات الأم -- تنفذ إضافات القنوات الإجراء النهائي عبر محوّل الإجراءات الخاص بها +- تملك النواة مضيف أداة `message` المشتركة، وربط المطالبات، وإدارة + الجلسات/المواضيع، وتوجيه التنفيذ +- تملك إضافات القنوات اكتشاف الإجراءات المقيّدة بالنطاق، واكتشاف + الإمكانات، وأي أجزاء مخطط خاصة بالقناة +- تملك إضافات القنوات قواعد محادثة الجلسات الخاصة بالمزوّد، مثل كيفية + ترميز معرّفات المحادثات لمعرّفات المواضيع أو وراثتها من المحادثات الأصلية +- تنفذ إضافات القنوات الإجراء النهائي عبر مكيّف الإجراءات الخاص بها -بالنسبة إلى إضافات القنوات، سطح SDK هو -`ChannelMessageActionAdapter.describeMessageTool(...)`. تسمح مكالمة -الاكتشاف الموحدة هذه للإضافة بإرجاع إجراءاتها المرئية وقدراتها ومساهماتها -في المخطط معًا حتى لا تنحرف هذه الأجزاء عن بعضها. +بالنسبة إلى إضافات القنوات، فإن سطح SDK هو +`ChannelMessageActionAdapter.describeMessageTool(...)`. يتيح استدعاء +الاكتشاف الموحد هذا للإضافة إعادة إجراءاتها المرئية وإمكاناتها ومساهماتها +في المخطط معًا بحيث لا تنجرف هذه الأجزاء عن بعضها. -تمرر النواة النطاق وقت التشغيل إلى خطوة الاكتشاف هذه. وتشمل الحقول المهمة: +تمرر النواة نطاق وقت التشغيل إلى خطوة الاكتشاف هذه. وتشمل الحقول المهمة: - `accountId` - `currentChannelId` @@ -190,124 +193,128 @@ x-i18n: - `sessionKey` - `sessionId` - `agentId` -- `requesterSenderId` الوارد الموثوق +- `requesterSenderId` الموثوق الوارد -وهذا مهم للإضافات الحساسة للسياق. يمكن للقناة إخفاء أو إظهار -إجراءات الرسائل بناءً على الحساب النشط أو الغرفة/الخيط/الرسالة الحالية أو -هوية الطالب الموثوقة، من دون ترميز فروع خاصة بالقناة داخل -أداة `message` الأساسية. +وهذا مهم للإضافات الحساسة للسياق. يمكن للقناة إخفاء إجراءات الرسائل أو +إظهارها بناءً على الحساب النشط أو الغرفة/الموضوع/الرسالة الحالية أو هوية +الطالب الموثوقة، من دون ترميز فروع خاصة بالقناة داخل أداة `message` في +النواة. -لهذا السبب تظل تغييرات التوجيه في المشغل المضمّن عملًا خاصًا بالإضافة: فالمشغل -مسؤول عن تمرير هوية الدردشة/الجلسة الحالية إلى حد الاكتشاف الخاص بالإضافة -حتى تكشف أداة `message` المشتركة السطح الصحيح المملوك للقناة للدور الحالي. +ولهذا السبب، تظل تغييرات التوجيه في العارض المضمّن عملًا خاصًا +بالإضافة: فالعارض مسؤول عن تمرير هوية الدردشة/الجلسة الحالية إلى حد +اكتشاف الإضافة بحيث تكشف أداة `message` المشتركة السطح المملوك للقناة +الصحيح للدور الحالي. -أما بالنسبة إلى مساعدات التنفيذ المملوكة للقنوات، فيجب على الإضافات المجمعة أن تُبقي -وقت تشغيل التنفيذ داخل وحدات الامتداد الخاصة بها. لم تعد النواة تملك أوقات تشغيل -إجراءات رسائل Discord أو Slack أو Telegram أو WhatsApp ضمن `src/agents/tools`. -ولا ننشر مسارات فرعية منفصلة من `plugin-sdk/*-action-runtime`، ويجب على -الإضافات المجمعة استيراد شيفرة وقت التشغيل المحلية الخاصة بها مباشرةً من -وحداتها المملوكة للامتداد. +وبالنسبة إلى مساعدات التنفيذ المملوكة للقناة، ينبغي أن تحتفظ الإضافات +المضمّنة بوقت تشغيل التنفيذ داخل وحدات الامتداد الخاصة بها. لم تعد النواة +تملك أزمنة تشغيل إجراءات الرسائل لـ Discord أو Slack أو Telegram أو +WhatsApp ضمن `src/agents/tools`. ولا ننشر مسارات فرعية منفصلة +`plugin-sdk/*-action-runtime`، وينبغي أن تستورد الإضافات المضمّنة شيفرة +وقت التشغيل المحلية الخاصة بها مباشرةً من وحداتها المملوكة للامتداد. -وينطبق الحد نفسه عمومًا على الوصلات المسماة بحسب المزود في SDK: لا ينبغي -للنواة أن تستورد حاويات تسهيلية خاصة بقنوات Slack أو Discord أو Signal أو -WhatsApp أو امتدادات مشابهة. وإذا احتاجت النواة إلى سلوك ما، فإما أن تستهلك -حاوية `api.ts` / `runtime-api.ts` الخاصة بالإضافة المجمعة نفسها أو ترفع الحاجة -إلى قدرة عامة ضيقة في SDK المشترك. +وينطبق الحد نفسه على فجوات SDK المسماة بأسماء المزوّدين عمومًا: لا ينبغي +للنواة أن تستورد حاويات ملائمة خاصة بالقنوات لـ Slack أو Discord أو Signal +أو WhatsApp أو الامتدادات المشابهة. وإذا احتاجت النواة إلى سلوك ما، +فإما أن تستهلك الحاوية `api.ts` / `runtime-api.ts` الخاصة بالإضافة +المضمّنة نفسها، أو ترقّي الحاجة إلى إمكانية عامة ضيقة في SDK المشترك. وبالنسبة إلى الاستطلاعات تحديدًا، هناك مساران للتنفيذ: - `outbound.sendPoll` هو خط الأساس المشترك للقنوات التي تناسب نموذج - الاستطلاع العام -- `actions.handleAction("poll")` هو المسار المفضل لدلالات الاستطلاع الخاصة بالقناة - أو لمعلمات الاستطلاع الإضافية + الاستطلاع الشائع +- `actions.handleAction("poll")` هو المسار المفضّل لدلالات الاستطلاع + الخاصة بالقناة أو لمعاملات الاستطلاع الإضافية -تؤجل النواة الآن تحليل الاستطلاع المشترك إلى ما بعد رفض توزيع استطلاع الإضافة -للإجراء، بحيث يمكن لمعالجات الاستطلاع المملوكة للإضافة قبول حقول -استطلاع خاصة بالقناة من دون أن يسبقها محلل الاستطلاع العام ويمنعها. +تؤجل النواة الآن تحليل الاستطلاع المشترك إلى ما بعد رفض إرسال الاستطلاع +من الإضافة، بحيث يمكن لمعالجات الاستطلاع المملوكة للإضافة قبول حقول +استطلاع خاصة بالقناة من دون أن يمنعها محلل الاستطلاع العام أولًا. -راجع [مسار التحميل](#load-pipeline) للتسلسل الكامل عند بدء التشغيل. +راجع [مسار التحميل](#load-pipeline) للاطلاع على تسلسل بدء التشغيل الكامل. -## نموذج ملكية القدرات +## نموذج ملكية الإمكانات -يتعامل OpenClaw مع الإضافة الأصلية على أنها حد ملكية لـ **شركة** أو -**ميزة**، لا مجرد حاوية لتكاملات غير مترابطة. +يتعامل OpenClaw مع الإضافة الأصلية بوصفها حدّ الملكية لشركة **company** أو +**feature**، وليس كمجموعة عشوائية من التكاملات غير المرتبطة. -هذا يعني: +وهذا يعني: -- يجب أن تملك إضافة الشركة عادةً كل الأسطح المواجهة لـ OpenClaw الخاصة بتلك الشركة -- يجب أن تملك إضافة الميزة عادةً سطح الميزة الكامل الذي تقدمه -- يجب أن تستهلك القنوات القدرات الأساسية المشتركة بدلًا من إعادة تنفيذ - سلوك المزود بصورة مخصصة +- ينبغي عادةً أن تملك إضافة الشركة جميع أسطح OpenClaw الخاصة بهذه الشركة +- ينبغي عادةً أن تملك إضافة الميزة السطح الكامل للميزة التي تقدمها +- ينبغي للقنوات أن تستهلك الإمكانات المشتركة في النواة بدلًا من إعادة + تنفيذ سلوك المزوّد بصورة مخصصة أمثلة: -- الإضافة المجمعة `openai` تملك سلوك مزود نماذج OpenAI وكذلك سلوك - OpenAI للكلام + الصوت الفوري + فهم الوسائط + توليد الصور -- الإضافة المجمعة `elevenlabs` تملك سلوك الكلام الخاص بـ ElevenLabs -- الإضافة المجمعة `microsoft` تملك سلوك الكلام الخاص بـ Microsoft -- الإضافة المجمعة `google` تملك سلوك مزود نماذج Google بالإضافة إلى +- تملك الإضافة المضمّنة `openai` سلوك مزوّد نماذج OpenAI، وسلوك OpenAI + للكلام + الصوت الفوري + فهم الوسائط + توليد الصور +- تملك الإضافة المضمّنة `elevenlabs` سلوك كلام ElevenLabs +- تملك الإضافة المضمّنة `microsoft` سلوك كلام Microsoft +- تملك الإضافة المضمّنة `google` سلوك مزوّد نماذج Google بالإضافة إلى سلوك Google لفهم الوسائط + توليد الصور + البحث في الويب -- الإضافة المجمعة `firecrawl` تملك سلوك جلب الويب الخاص بـ Firecrawl -- الإضافات المجمعة `minimax` و`mistral` و`moonshot` و`zai` تملك - الواجهات الخلفية الخاصة بها لفهم الوسائط -- الإضافة `voice-call` هي إضافة ميزات: فهي تملك نقل المكالمات والأدوات - وCLI والمسارات وجسر تدفق الوسائط من Twilio، لكنها تستهلك - القدرات المشتركة للكلام + النسخ الفوري + الصوت الفوري بدلًا من - استيراد إضافات المورد مباشرة +- تملك الإضافة المضمّنة `firecrawl` سلوك جلب الويب الخاص بـ Firecrawl +- تملك الإضافات المضمّنة `minimax` و`mistral` و`moonshot` و`zai` + واجهاتها الخلفية لفهم الوسائط +- تملك الإضافة المضمّنة `qwen` سلوك مزوّد النص لـ Qwen بالإضافة إلى + سلوك فهم الوسائط وتوليد الفيديو +- إضافة `voice-call` هي إضافة ميزة: فهي تملك نقل المكالمات، والأدوات، + وCLI، والمسارات، وجسر تدفقات وسائط Twilio، لكنها تستهلك إمكانات الكلام + المشتركة بالإضافة إلى النسخ الفوري والصوت الفوري بدلًا من استيراد + إضافات المورّدين مباشرةً الحالة النهائية المقصودة هي: -- يعيش OpenAI في إضافة واحدة حتى لو امتد إلى نماذج النص والكلام والصور +- تعيش OpenAI داخل إضافة واحدة حتى لو كانت تمتد عبر نماذج النص والكلام والصور والفيديو مستقبلًا -- ويمكن لمورد آخر أن يفعل الشيء نفسه لمساحته الخاصة -- ولا تهتم القنوات بأي إضافة مورد تملك المزود؛ بل تستهلك عقد - القدرة المشتركة التي تكشفها النواة +- يمكن لمورّد آخر أن يفعل الشيء نفسه لمساحة السطح الخاصة به +- لا تهتم القنوات بأي إضافة مورّد تملك المزوّد؛ فهي تستهلك عقد + الإمكانات المشتركة الذي تكشفه النواة وهذا هو التمييز الأساسي: -- **plugin** = حد الملكية +- **plugin** = حدّ الملكية - **capability** = عقد النواة الذي يمكن لعدة إضافات تنفيذه أو استهلاكه -لذلك إذا أضاف OpenClaw مجالًا جديدًا مثل الفيديو، فالسؤال الأول ليس -"أي مزود يجب أن يرمّز التعامل مع الفيديو؟" بل السؤال الأول هو: "ما -هو عقد قدرة الفيديو الأساسية؟" وبمجرد وجود هذا العقد، تستطيع إضافات المورد -التسجيل مقابله ويمكن لإضافات القنوات/الميزات استهلاكه. +لذلك إذا أضاف OpenClaw مجالًا جديدًا مثل الفيديو، فإن السؤال الأول ليس: +"أي مزوّد ينبغي أن يضمّن معالجة الفيديو في شيفرته؟" السؤال الأول هو: "ما +هو عقد إمكانات الفيديو في النواة؟" وبمجرد وجود هذا العقد، يمكن لإضافات +المورّدين التسجيل عليه، ويمكن لإضافات القنوات/الميزات استهلاكه. -إذا لم تكن القدرة موجودة بعد، فالخطوة الصحيحة غالبًا هي: +وإذا لم تكن الإمكانية موجودة بعد، فعادةً ما تكون الخطوة الصحيحة هي: -1. تعريف القدرة المفقودة في النواة -2. كشفها عبر واجهة برمجة الإضافة/وقت التشغيل بطريقة مكتوبة الأنواع -3. توصيل القنوات/الميزات بهذه القدرة -4. ترك إضافات المورد تسجل التنفيذات +1. تعريف الإمكانية المفقودة في النواة +2. كشفها عبر واجهة API/وقت التشغيل الخاصة بالإضافة بطريقة مكتوبة Typed +3. ربط القنوات/الميزات بهذه الإمكانية +4. السماح لإضافات المورّدين بتسجيل التنفيذات -يحافظ ذلك على وضوح الملكية ويجنب سلوك النواة الذي يعتمد على -مورد واحد أو مسار شيفرة خاص بإضافة واحدة. +وهذا يُبقي الملكية صريحة مع تجنب سلوك في النواة يعتمد على مورّد واحد أو +مسار شيفرة خاص بإضافة واحدة فقط. -### طبقات القدرات +### طبقات الإمكانات -استخدم هذا النموذج الذهني عند اتخاذ قرار بشأن موضع الشيفرة: +استخدم هذا النموذج الذهني عند تقرير مكان انتماء الشيفرة: -- **طبقة القدرة الأساسية**: التنسيق المشترك والسياسات وآليات التراجع وقواعد - دمج الإعدادات ودلالات التسليم والعقود المكتوبة الأنواع -- **طبقة إضافة المورد**: واجهات API الخاصة بالمورد والمصادقة وكتالوجات النماذج - وتوليف الكلام وتوليد الصور وواجهات الفيديو الخلفية مستقبلًا ونقاط استخدام الخدمة -- **طبقة إضافة القناة/الميزة**: تكاملات Slack/Discord/voice-call/etc. - التي تستهلك القدرات الأساسية وتعرضها على سطح معين +- **طبقة الإمكانات في النواة**: التنسيق المشترك، والسياسات، وآليات + التراجع، وقواعد دمج الإعدادات، ودلالات التسليم، والعقود المكتوبة Typed +- **طبقة إضافات المورّدين**: واجهات API الخاصة بالمورّد، والمصادقة، + وكتالوجات النماذج، وتركيب الكلام، وتوليد الصور، وواجهات الفيديو الخلفية + مستقبلًا، ونقاط نهاية الاستخدام +- **طبقة إضافات القنوات/الميزات**: تكامل Slack/Discord/voice-call/إلخ + الذي يستهلك إمكانات النواة ويعرضها على سطح معيّن على سبيل المثال، يتبع TTS هذا الشكل: -- تملك النواة سياسة TTS وقت الرد وترتيب التراجع والتفضيلات وتسليم القنوات -- وتملك `openai` و`elevenlabs` و`microsoft` تنفيذات التوليف -- وتستهلك `voice-call` مساعد وقت تشغيل TTS للهاتف +- تملك النواة سياسة TTS وقت الرد، وترتيب التراجع، والتفضيلات، وتسليم القناة +- تملك `openai` و`elevenlabs` و`microsoft` تنفيذات التركيب +- تستهلك `voice-call` مساعد وقت تشغيل TTS الخاص بالهاتف -ويجب تفضيل هذا النمط نفسه للقدرات المستقبلية. +ويُفضّل اعتماد هذا النمط نفسه للإمكانات المستقبلية. -### مثال على إضافة شركة متعددة القدرات +### مثال على إضافة شركة متعددة الإمكانات -يجب أن تبدو إضافة الشركة متماسكة من الخارج. إذا كان لدى OpenClaw -عقود مشتركة للنماذج والكلام والنسخ الفوري والصوت الفوري وفهم -الوسائط وتوليد الصور وتوليد الفيديو وجلب الويب والبحث في الويب، -فيمكن لمورد ما أن يملك كل أسطحه في مكان واحد: +ينبغي أن تبدو إضافة الشركة متماسكة من الخارج. فإذا كان لدى OpenClaw عقود +مشتركة للنماذج، والكلام، والنسخ الفوري، والصوت الفوري، وفهم الوسائط، +وتوليد الصور، وتوليد الفيديو، وجلب الويب، والبحث في الويب، فيمكن لمورّد +أن يملك جميع أسطحه في مكان واحد: ```ts import type { OpenClawPluginDefinition } from "openclaw/plugin-sdk/plugin-entry"; @@ -322,12 +329,12 @@ const plugin: OpenClawPluginDefinition = { register(api) { api.registerProvider({ id: "exampleai", - // خطافات وقت التشغيل/كتالوج النماذج/المصادقة + // auth/model catalog/runtime hooks }); api.registerSpeechProvider({ id: "exampleai", - // إعدادات الكلام الخاصة بالمورد — نفّذ واجهة SpeechProviderPlugin مباشرةً + // vendor speech config — implement the SpeechProviderPlugin interface directly }); api.registerMediaUnderstandingProvider({ @@ -352,7 +359,7 @@ const plugin: OpenClawPluginDefinition = { api.registerWebSearchProvider( createPluginBackedWebSearchProvider({ id: "exampleai-search", - // منطق بيانات الاعتماد + الجلب + // credential + fetch logic }), ); }, @@ -361,224 +368,234 @@ const plugin: OpenClawPluginDefinition = { export default plugin; ``` -المهم ليس أسماء المساعدات الدقيقة. بل الشكل: +المهم ليس أسماء المساعدات الدقيقة. المهم هو الشكل: -- إضافة واحدة تملك سطح المورد -- النواة تظل هي مالكة عقود القدرات -- القنوات وإضافات الميزات تستهلك مساعدات `api.runtime.*`، لا شيفرة المورد -- يمكن لاختبارات العقود التحقق من أن الإضافة سجلت القدرات التي - تدّعي امتلاكها +- إضافة واحدة تملك سطح المورّد +- لا تزال النواة تملك عقود الإمكانات +- تستهلك إضافات القنوات والميزات مساعدات `api.runtime.*`، لا شيفرة المورّد +- يمكن لاختبارات العقود أن تؤكد أن الإضافة سجّلت الإمكانات التي تدّعي + امتلاكها -### مثال على القدرة: فهم الفيديو +### مثال على الإمكانية: فهم الفيديو -يعامل OpenClaw بالفعل فهم الصور/الصوت/الفيديو على أنه قدرة مشتركة واحدة. -وينطبق نموذج الملكية نفسه هنا: +يتعامل OpenClaw بالفعل مع فهم الصور/الصوت/الفيديو على أنه إمكانية مشتركة +واحدة. وينطبق نموذج الملكية نفسه هنا: 1. تعرّف النواة عقد فهم الوسائط -2. تسجل إضافات المورد `describeImage` و`transcribeAudio` و - `describeVideo` بحسب الاقتضاء -3. تستهلك القنوات وإضافات الميزات السلوك الأساسي المشترك بدلًا من - الربط المباشر مع شيفرة المورد +2. تسجّل إضافات المورّدين `describeImage` و`transcribeAudio` و + `describeVideo` حسب الاقتضاء +3. تستهلك إضافات القنوات والميزات سلوك النواة المشترك بدلًا من الربط + المباشر مع شيفرة المورّد -وهذا يمنع ترسيخ افتراضات مورد واحد بشأن الفيديو داخل النواة. فالإضافة -تملك سطح المورد؛ والنواة تملك عقد القدرة وسلوك التراجع. +ويمنع هذا ترسيخ افتراضات الفيديو الخاصة بمزوّد واحد داخل النواة. فالإضافة +تملك سطح المورّد؛ بينما تملك النواة عقد الإمكانية وسلوك التراجع. -ويتبع توليد الفيديو التسلسل نفسه بالفعل: فالنواة تملك عقد -القدرة المكتوب الأنواع ومساعد وقت التشغيل، وتسجل إضافات المورد -تنفيذات `api.registerVideoGenerationProvider(...)` مقابله. +ويستخدم توليد الفيديو بالفعل هذا التسلسل نفسه: تملك النواة عقد الإمكانية +المكتوب Typed ومساعد وقت التشغيل، وتسجّل إضافات المورّدين تنفيذات +`api.registerVideoGenerationProvider(...)` عليه. -هل تحتاج إلى قائمة تحقق عملية للطرح؟ راجع -[دفتر وصفات القدرات](/ar/plugins/architecture). +هل تحتاج إلى قائمة تحقق عملية واضحة لطرح ذلك؟ راجع +[دليل الإمكانات العملي](/ar/plugins/architecture). ## العقود والإنفاذ -سطح واجهة برمجة الإضافة مكتوب الأنواع ومركزي عمدًا في -`OpenClawPluginApi`. ويعرّف هذا العقد نقاط التسجيل المدعومة -ومساعدات وقت التشغيل التي يمكن أن تعتمد عليها الإضافة. +سطح واجهة API للإضافات مكتوب Typed ومركزي عمدًا في +`OpenClawPluginApi`. يعرّف هذا العقد نقاط التسجيل المدعومة ومساعدات وقت +التشغيل التي يمكن للإضافة الاعتماد عليها. -سبب أهمية ذلك: +لماذا يهم ذلك: - يحصل مؤلفو الإضافات على معيار داخلي ثابت واحد -- تستطيع النواة رفض الملكية المكررة، مثل تسجيل إضافتين للمعرف نفسه - للمزود -- يمكن لبدء التشغيل إظهار تشخيصات عملية للتسجيلات غير الصحيحة -- يمكن لاختبارات العقود فرض ملكية الإضافات المجمعة ومنع الانحراف الصامت +- يمكن للنواة رفض الملكية المكررة، مثل تسجيل إضافتين لمعرّف المزوّد نفسه +- يمكن لبدء التشغيل إظهار تشخيصات عملية للتسجيلات غير السليمة +- يمكن لاختبارات العقود فرض ملكية الإضافات المضمّنة ومنع الانجراف الصامت هناك طبقتان من الإنفاذ: -1. **إنفاذ التسجيل وقت التشغيل** - يتحقق سجل الإضافات من التسجيلات أثناء تحميل الإضافات. أمثلة: - معرفات المزود المكررة، ومعرفات مزود الكلام المكررة، والتسجيلات - غير الصحيحة تؤدي إلى تشخيصات للإضافات بدلًا من سلوك غير معرّف. +1. **إنفاذ التسجيل في وقت التشغيل** + يتحقق سجل الإضافات من التسجيلات أثناء تحميل الإضافات. من الأمثلة: + معرّفات المزوّدين المكررة، ومعرّفات مزوّدي الكلام المكررة، والتسجيلات + غير السليمة التي تنتج تشخيصات للإضافة بدلًا من سلوك غير معرّف. 2. **اختبارات العقود** - تُلتقط الإضافات المجمعة في سجلات العقود أثناء تشغيل الاختبارات حتى - يتمكن OpenClaw من تأكيد الملكية بشكل صريح. ويُستخدم هذا اليوم مع - مزودي النماذج، ومزودي الكلام، ومزودي البحث في الويب، وملكية التسجيل المجمعة. + تُلتقط الإضافات المضمّنة في سجلات عقود أثناء تشغيل الاختبارات حتى يتمكن + OpenClaw من تأكيد الملكية صراحةً. ويُستخدم هذا اليوم لمزوّدي النماذج، + ومزوّدي الكلام، ومزوّدي البحث في الويب، وملكية التسجيلات المضمّنة. -الأثر العملي هو أن OpenClaw يعرف مسبقًا أي إضافة تملك أي -سطح. ويسمح ذلك للنواة والقنوات بالتأليف بسلاسة لأن الملكية -معلنة ومكتوبة الأنواع وقابلة للاختبار بدل أن تكون ضمنية. +والأثر العملي لذلك هو أن OpenClaw يعرف مسبقًا أي إضافة تملك أي سطح. وهذا +يمكّن النواة والقنوات من التركيب بسلاسة لأن الملكية مُعلنة ومكتوبة وقابلة +للاختبار بدلًا من أن تكون ضمنية. -### ما الذي يجب أن يكون ضمن العقد +### ما الذي يجب أن ينتمي إلى عقد عقود الإضافات الجيدة تكون: -- مكتوبة الأنواع +- مكتوبة Typed - صغيرة -- خاصة بالقدرات +- خاصة بالإمكانية - مملوكة للنواة - قابلة لإعادة الاستخدام من عدة إضافات -- قابلة للاستهلاك من القنوات/الميزات من دون معرفة المورد +- قابلة للاستهلاك من القنوات/الميزات من دون معرفة بالمورّد أما عقود الإضافات السيئة فهي: -- سياسة خاصة بالمورد مخفية داخل النواة -- منافذ هروب لمرة واحدة تتجاوز السجل -- شيفرة قناة تصل مباشرة إلى تنفيذ خاص بمورد +- سياسات خاصة بالمورّد مخفية داخل النواة +- مخارج هروب خاصة بإضافة واحدة تتجاوز السجل +- شيفرة قناة تصل مباشرةً إلى تنفيذ خاص بمورّد - كائنات وقت تشغيل مخصصة ليست جزءًا من `OpenClawPluginApi` أو `api.runtime` -عند الشك، ارفع مستوى التجريد: عرّف القدرة أولًا، ثم دع الإضافات -تتصل بها. +وعند الشك، ارفع مستوى التجريد: عرّف الإمكانية أولًا، ثم دع الإضافات تتصل +بها. ## نموذج التنفيذ -تعمل إضافات OpenClaw الأصلية **داخل العملية** مع Gateway. وهي غير -معزولة. وتملك الإضافة الأصلية المحمّلة حد الثقة على مستوى العملية نفسه -الخاص بشيفرة النواة. +تعمل إضافات OpenClaw الأصلية **داخل العملية** مع Gateway. وهي ليست +معزولة. فالإضافة الأصلية المحمّلة تمتلك حد الثقة نفسه على مستوى العملية +مثل شيفرة النواة. الآثار المترتبة: -- يمكن للإضافة الأصلية تسجيل أدوات ومعالجات شبكة وخطافات وخدمات -- يمكن لخلل في إضافة أصلية أن يعطل البوابة أو يزعزع استقرارها -- الإضافة الأصلية الخبيثة تعادل تنفيذ شيفرة عشوائية داخل عملية - OpenClaw +- يمكن للإضافة الأصلية تسجيل الأدوات، ومعالجات الشبكة، والخطافات، والخدمات +- يمكن لخطأ في إضافة أصلية أن يتسبب في تعطل gateway أو زعزعة استقراره +- تعادل الإضافة الأصلية الخبيثة تنفيذ شيفرة عشوائية داخل عملية OpenClaw -تكون الحزم المتوافقة أكثر أمانًا افتراضيًا لأن OpenClaw يتعامل معها حاليًا -على أنها حزم بيانات وصفية/محتوى. وفي الإصدارات الحالية، يعني ذلك غالبًا -Skills المجمعة. +الحِزم المتوافقة أكثر أمانًا افتراضيًا لأن OpenClaw يتعامل معها حاليًا على +أنها حِزم بيانات وصفية/محتوى. وفي الإصدارات الحالية، يعني ذلك في الغالب +المهارات المضمّنة. -استخدم قوائم السماح ومسارات التثبيت/التحميل الصريحة للإضافات غير المجمعة. -وتعامل مع إضافات مساحة العمل على أنها شيفرة وقت تطوير، لا إعدادات -إنتاجية افتراضية. +استخدم قوائم السماح ومسارات التثبيت/التحميل الصريحة للإضافات غير المضمّنة. +وتعامل مع إضافات مساحة العمل على أنها شيفرة وقت تطوير، لا افتراضات إنتاج. -وبالنسبة إلى أسماء حزم مساحة العمل المجمعة، اجعل معرف الإضافة مرتكزًا في اسم npm: -`@openclaw/` افتراضيًا، أو لاحقة نوعية معتمدة مثل -`-provider` أو `-plugin` أو `-speech` أو `-sandbox` أو `-media-understanding` عندما -تكشف الحزمة عمدًا دور إضافة أضيق. +وبالنسبة إلى أسماء حِزم مساحة العمل المضمّنة، أبقِ معرّف الإضافة مثبتًا في +اسم npm: `@openclaw/` افتراضيًا، أو لاحقة مكتوبة معتمدة مثل +`-provider` أو `-plugin` أو `-speech` أو `-sandbox` أو +`-media-understanding` عندما تكشف الحزمة عمدًا دور إضافة أضيق. ملاحظة ثقة مهمة: -- `plugins.allow` يثق في **معرفات الإضافات**، لا في مصدرها. -- إضافة مساحة عمل تحمل المعرف نفسه لإضافة مجمعة ستُظلّل عمدًا - النسخة المجمعة عندما تكون إضافة مساحة العمل مُمكّنة/ضمن قائمة السماح. -- وهذا سلوك طبيعي ومفيد للتطوير المحلي واختبار التصحيحات والإصلاحات العاجلة. +- يثق `plugins.allow` في **معرّفات الإضافات**، وليس في مصدر المنشأ. +- تعمّد إضافة مساحة عمل لها المعرّف نفسه كإضافة مضمّنة إلى تظليل النسخة + المضمّنة عندما تكون إضافة مساحة العمل تلك مفعّلة/ضمن قائمة السماح. +- هذا سلوك طبيعي ومفيد للتطوير المحلي، واختبار التصحيحات، والإصلاحات + العاجلة. -## حد التصدير +## حدّ التصدير -يصدّر OpenClaw القدرات، لا تسهيلات التنفيذ. +يصدر OpenClaw الإمكانات، لا وسائل الراحة الخاصة بالتنفيذ. -أبقِ تسجيل القدرات عامًا. وقلّم صادرات المساعدات غير التعاقدية: +أبقِ تسجيل الإمكانات عامًا. وقلّص صادرات المساعدة غير التعاقدية: -- المسارات الفرعية الخاصة بمساعدات الإضافات المجمعة -- المسارات الفرعية الخاصة بتوصيلات وقت التشغيل غير المقصودة كواجهة API عامة -- المساعدات التسهيلية الخاصة بالمورد -- مساعدات الإعداد/التهيئة التي تُعد تفاصيل تنفيذ +- المسارات الفرعية الخاصة بمساعدة الإضافات المضمّنة +- المسارات الفرعية الخاصة ببنية وقت التشغيل غير المقصود بها أن تكون API + عامة +- وسائل الراحة الخاصة بالمورّد +- مساعدات الإعداد/التهيئة التي تعد تفاصيل تنفيذ -لا تزال بعض المسارات الفرعية المساعدة للإضافات المجمعة موجودة في خريطة -صادرات SDK المولدة من أجل التوافق وصيانة الإضافات المجمعة. ومن الأمثلة الحالية -`plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, -`plugin-sdk/zalo-setup`, والعديد من وصلات `plugin-sdk/matrix*`. تعامل مع هذه -المسارات على أنها صادرات محجوزة تمثل تفاصيل تنفيذ، لا النمط الموصى به في SDK -للإضافات الخارجية الجديدة. +لا تزال بعض المسارات الفرعية المساعدة للإضافات المضمّنة موجودة في خريطة +صادرات SDK المولّدة لأسباب تتعلق بالتوافق وصيانة الإضافات المضمّنة. تشمل +الأمثلة الحالية `plugin-sdk/feishu` و`plugin-sdk/feishu-setup` و +`plugin-sdk/zalo` و`plugin-sdk/zalo-setup` وعدة فجوات +`plugin-sdk/matrix*`. تعامل مع هذه على أنها صادرات محجوزة خاصة بتفاصيل +التنفيذ، لا النمط الموصى به لـ SDK لإضافات الطرف الثالث الجديدة. ## مسار التحميل -عند بدء التشغيل، يقوم OpenClaw تقريبًا بما يلي: +عند بدء التشغيل، يفعل OpenClaw تقريبًا ما يلي: -1. اكتشاف جذور الإضافات المرشحة -2. قراءة بيانات الإضافات الأصلية أو الحزم المتوافقة وبيانات الحزم الوصفية -3. رفض المرشحين غير الآمنين -4. تطبيع إعدادات الإضافات (`plugins.enabled`, `allow`, `deny`, `entries`, +1. يكتشف جذور الإضافات المرشحة +2. يقرأ بيانات الإضافات الأصلية أو الحِزم المتوافقة وبيانات الحزمة الوصفية +3. يرفض المرشحين غير الآمنين +4. يطبّع إعدادات الإضافات (`plugins.enabled`, `allow`, `deny`, `entries`, `slots`, `load.paths`) -5. تقرير التمكين لكل مرشح -6. تحميل الوحدات الأصلية المفعلة عبر jiti -7. استدعاء خطافات `register(api)` الأصلية (أو `activate(api)` — وهو اسم مستعار قديم) وجمع التسجيلات في سجل الإضافات -8. كشف السجل إلى الأوامر/أسطح وقت التشغيل +5. يقرر التمكين لكل مرشح +6. يحمّل الوحدات الأصلية الممكّنة عبر jiti +7. يستدعي خطافات `register(api)` الأصلية (أو `activate(api)` — وهو اسم + بديل قديم) ويجمع التسجيلات في سجل الإضافات +8. يكشف السجل لأسطح الأوامر/وقت التشغيل -`activate` اسم مستعار قديم لـ `register` — يقوم المحمل بحل أيٍّ منهما موجود (`def.register ?? def.activate`) ويستدعيه في النقطة نفسها. تستخدم جميع الإضافات المجمعة `register`; ويفضَّل استخدام `register` في الإضافات الجديدة. +`activate` هو اسم بديل قديم لـ `register` — يقوم المحمّل بحل أيهما موجود +(`def.register ?? def.activate`) ويستدعيه في النقطة نفسها. تستخدم جميع +الإضافات المضمّنة `register`؛ ويفضّل استخدام `register` للإضافات الجديدة. -تحدث بوابات الأمان **قبل** تنفيذ وقت التشغيل. ويُحظر المرشحون -عندما يفلت الإدخال من جذر الإضافة، أو يكون المسار قابلاً للكتابة من الجميع، -أو تبدو ملكية المسار مشبوهة بالنسبة إلى الإضافات غير المجمعة. +تحدث بوابات الأمان **قبل** تنفيذ وقت التشغيل. ويُحظر المرشحون عندما يفلت +المدخل من جذر الإضافة، أو يكون المسار قابلاً للكتابة من الجميع، أو تبدو +ملكية المسار مشبوهة بالنسبة إلى الإضافات غير المضمّنة. ### سلوك البيان أولًا البيان هو مصدر الحقيقة في مستوى التحكم. يستخدمه OpenClaw من أجل: - تحديد الإضافة -- اكتشاف القنوات/Skills/مخطط الإعدادات أو قدرات الحزمة المعلنة +- اكتشاف القنوات/المهارات/مخطط الإعدادات أو إمكانات الحزمة المعلنة - التحقق من `plugins.entries..config` - تعزيز تسميات/عناصر نائبة في Control UI -- إظهار بيانات التثبيت/الكتالوج الوصفية +- عرض بيانات التثبيت/الكتالوج الوصفية +- الحفاظ على واصفات تفعيل وإعداد منخفضة الكلفة من دون تحميل وقت تشغيل + الإضافة -أما بالنسبة إلى الإضافات الأصلية، فتمثل وحدة وقت التشغيل جزء مستوى البيانات. فهي -تسجل السلوك الفعلي مثل الخطافات أو الأدوات أو الأوامر أو تدفقات المزود. +بالنسبة إلى الإضافات الأصلية، تكون وحدة وقت التشغيل هي جزء مستوى البيانات. +فهي تسجّل السلوك الفعلي مثل الخطافات، والأدوات، والأوامر، أو تدفقات +المزوّد. -### ما الذي يخزنه المحمّل مؤقتًا +وتبقى الكتلتان الاختياريتان `activation` و`setup` في البيان ضمن مستوى +التحكم. فهما واصفات بيانات وصفية فقط لتخطيط التفعيل واكتشاف الإعداد؛ ولا +تحلان محل التسجيل في وقت التشغيل أو `register(...)` أو `setupEntry`. -يحتفظ OpenClaw بمخابئ قصيرة العمر داخل العملية لما يلي: +### ما الذي يخزّنه المحمّل مؤقتًا + +يحتفظ OpenClaw بذاكرات مؤقتة قصيرة داخل العملية من أجل: - نتائج الاكتشاف - بيانات سجل البيان -- سجلات الإضافات المحملة +- سجلات الإضافات المحمّلة -تقلل هذه المخابئ من الاندفاعات عند بدء التشغيل ومن كلفة الأوامر المتكررة. ومن -الآمن اعتبارها مخابئ أداء قصيرة العمر، لا طبقة استمرارية. +تقلل هذه الذواكر المؤقتة من اندفاعات بدء التشغيل ومن كلفة الأوامر +المتكررة. ومن الآمن التفكير فيها على أنها ذواكر أداء مؤقتة قصيرة العمر، +لا تخزينًا دائمًا. -ملاحظة أداء: +ملاحظة حول الأداء: - اضبط `OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1` أو - `OPENCLAW_DISABLE_PLUGIN_MANIFEST_CACHE=1` لتعطيل هذه المخابئ. -- اضبط نوافذ المخابئ باستخدام `OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS` و + `OPENCLAW_DISABLE_PLUGIN_MANIFEST_CACHE=1` لتعطيل هذه الذواكر المؤقتة. +- اضبط نوافذ الذواكر المؤقتة عبر `OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS` و `OPENCLAW_PLUGIN_MANIFEST_CACHE_MS`. ## نموذج السجل -لا تقوم الإضافات المحملة بتعديل متغيرات النواة العامة العشوائية مباشرةً. بل -تسجّل نفسها في سجل إضافات مركزي. +لا تقوم الإضافات المحمّلة بتعديل متغيرات عامة عشوائية في النواة مباشرةً. +بل تسجّل في سجل إضافات مركزي. يتتبع السجل ما يلي: -- سجلات الإضافات (الهوية، المصدر، الأصل، الحالة، التشخيصات) +- سجلات الإضافات (الهوية، والمصدر، والمنشأ، والحالة، والتشخيصات) - الأدوات -- الخطافات القديمة والخطافات المكتوبة الأنواع +- الخطافات القديمة والخطافات المكتوبة Typed - القنوات -- المزودون +- المزوّدون - معالجات Gateway RPC - مسارات HTTP -- مسجلو CLI +- مسجّلات CLI - الخدمات الخلفية -- الأوامر المملوكة للإضافات +- الأوامر المملوكة للإضافة -ثم تقرأ ميزات النواة من هذا السجل بدلًا من التحدث إلى وحدات الإضافات -مباشرةً. وهذا يبقي التحميل في اتجاه واحد: +ثم تقرأ ميزات النواة من هذا السجل بدلًا من التحدث مباشرةً إلى وحدات +الإضافات. وهذا يبقي التحميل أحادي الاتجاه: - وحدة الإضافة -> التسجيل في السجل - وقت تشغيل النواة -> استهلاك السجل -ويهم هذا الفصل من أجل سهولة الصيانة. فهو يعني أن معظم أسطح النواة تحتاج -إلى نقطة تكامل واحدة فقط: "اقرأ السجل"، لا "أنشئ حالة خاصة لكل -وحدة إضافة". +هذا الفصل مهم من أجل القابلية للصيانة. فهو يعني أن معظم أسطح النواة تحتاج +فقط إلى نقطة تكامل واحدة: "اقرأ السجل"، وليس "ضع حالة خاصة لكل وحدة +إضافة". -## استدعاءات ربط المحادثات +## استدعاءات ربط المحادثة -يمكن للإضافات التي تربط محادثة أن تتفاعل عند حسم موافقة ما. +يمكن للإضافات التي تربط محادثة أن تتفاعل عند حسم الموافقة. -استخدم `api.onConversationBindingResolved(...)` لتلقي استدعاء -بعد الموافقة على طلب الربط أو رفضه: +استخدم `api.onConversationBindingResolved(...)` لتلقّي استدعاء بعد الموافقة +على طلب الربط أو رفضه: ```ts export default { @@ -586,12 +603,12 @@ export default { register(api) { api.onConversationBindingResolved(async (event) => { if (event.status === "approved") { - // يوجد الآن ربط لهذه الإضافة + المحادثة. + // A binding now exists for this plugin + conversation. console.log(event.binding?.conversationId); return; } - // تم رفض الطلب؛ امسح أي حالة محلية معلقة. + // The request was denied; clear any local pending state. console.log(event.request.conversation.conversationId); }); }, @@ -602,24 +619,25 @@ export default { - `status`: `"approved"` أو `"denied"` - `decision`: `"allow-once"` أو `"allow-always"` أو `"deny"` -- `binding`: الربط المحسوم للطلبات الموافق عليها -- `request`: ملخص الطلب الأصلي، وتلميح الفصل، ومعرف المرسِل، وبيانات +- `binding`: الربط الذي تم حسمه للطلبات الموافق عليها +- `request`: ملخص الطلب الأصلي، وتلميح الفصل، ومعرّف المرسل، وبيانات المحادثة الوصفية -هذا الاستدعاء مخصص للإشعارات فقط. ولا يغيّر من يملك صلاحية ربط -المحادثة، ويعمل بعد انتهاء معالجة الموافقة الأساسية. +هذا الاستدعاء مخصّص للإشعارات فقط. فهو لا يغيّر من يُسمح له بربط محادثة، +ويعمل بعد انتهاء معالجة الموافقة في النواة. -## خطافات وقت تشغيل المزود +## خطافات وقت تشغيل المزوّد -أصبحت إضافات المزود الآن ذات طبقتين: +تمتلك إضافات المزوّد الآن طبقتين: -- بيانات البيان الوصفية: `providerAuthEnvVars` للبحث الرخيص عن مصادقة - المزود في متغيرات البيئة قبل تحميل وقت التشغيل، و`providerAuthAliases` - لمتغيرات المزود التي تشترك في المصادقة، و`channelEnvVars` للبحث - الرخيص عن إعداد/مصادقة القناة عبر البيئة قبل تحميل وقت - التشغيل، بالإضافة إلى `providerAuthChoices` لتسميات اختيار المصادقة/التهيئة - الرخيصة وبيانات أعلام CLI الوصفية قبل تحميل وقت التشغيل -- خطافات وقت الإعداد: `catalog` / الاسم القديم `discovery` بالإضافة إلى `applyConfigDefaults` +- بيانات وصفية في البيان: `providerAuthEnvVars` لبحث سريع عن مصادقة + المزوّد من متغيرات البيئة قبل تحميل وقت التشغيل، و`providerAuthAliases` + لمتغيرات المزوّد التي تتشارك المصادقة، و`channelEnvVars` لبحث سريع عن + إعداد/مصادقة القناة من متغيرات البيئة قبل تحميل وقت التشغيل، بالإضافة إلى + `providerAuthChoices` لتسميات إعداد المستخدم/اختيار المصادقة الرخيصة + وبيانات CLI الوصفية الخاصة بالأعلام قبل تحميل وقت التشغيل +- خطافات وقت الإعدادات: `catalog` / `discovery` القديم بالإضافة إلى + `applyConfigDefaults` - خطافات وقت التشغيل: `normalizeModelId`, `normalizeTransport`, `normalizeConfig`, `applyNativeStreamingUsageCompat`, `resolveConfigApiKey`, @@ -640,91 +658,93 @@ export default { `buildReplayPolicy`, `sanitizeReplayHistory`, `validateReplayTurns`, `onModelSelected` -لا يزال OpenClaw يملك حلقة الوكيل العامة وآلية التراجع ومعالجة النصوص -وسياست الأدوات. وتمثل هذه الخطافات سطح الامتداد للسلوك الخاص بالمزود من دون -الحاجة إلى ناقل استدلال مخصص كامل. +لا يزال OpenClaw يملك حلقة الوكيل العامة، وآلية التبديل الاحتياطي، ومعالجة +النصوص، وسياسة الأدوات. وتمثل هذه الخطافات سطح التوسعة للسلوك الخاص +بالمزوّد من دون الحاجة إلى نقل استدلال مخصص كامل. -استخدم `providerAuthEnvVars` في البيان عندما يملك المزود بيانات اعتماد -معتمدة على البيئة يجب أن تراها مسارات المصادقة/الحالة/منتقي النماذج العامة -من دون تحميل وقت تشغيل الإضافة. واستخدم `providerAuthAliases` في البيان عندما -يجب أن يعيد معرّف مزود واحد استخدام متغيرات البيئة وملفات تعريف المصادقة -والمصادقة المدعومة بالإعدادات وخيار تهيئة مفتاح API الخاص بمعرف مزود آخر. واستخدم -`providerAuthChoices` في البيان عندما تحتاج أسطح CLI الخاصة بالتهيئة/اختيار المصادقة -إلى معرفة معرف خيار المزود وتسميات المجموعة الخاصة به وربط المصادقة البسيط -المعتمد على علم واحد من دون تحميل وقت تشغيل المزود. واحتفظ بمتغيرات البيئة -الخاصة بوقت تشغيل المزود `envVars` من أجل التلميحات الموجهة للمشغل مثل -تسميات التهيئة أو متغيرات إعداد `client-id`/`client-secret` الخاصة بـ OAuth. +استخدم `providerAuthEnvVars` في البيان عندما يمتلك المزوّد بيانات اعتماد +قائمة على متغيرات البيئة ينبغي لمسارات المصادقة/الحالة/منتقي النموذج +العامة رؤيتها من دون تحميل وقت تشغيل الإضافة. واستخدم +`providerAuthAliases` في البيان عندما ينبغي لمعرّف مزوّد واحد أن يعيد +استخدام متغيرات البيئة وملفات تعريف المصادقة والمصادقة القائمة على +الإعدادات وخيار إعداد مفتاح API الخاص بمعرّف مزوّد آخر. واستخدم +`providerAuthChoices` في البيان عندما ينبغي لأسطح CLI الخاصة بإعداد +المستخدم/اختيار المصادقة أن تعرف معرّف اختيار المزوّد وتسميات المجموعة +والربط البسيط للمصادقة بعَلَم واحد من دون تحميل وقت تشغيل المزوّد. وأبقِ +`envVars` في وقت تشغيل المزوّد لتلميحات المشغّل مثل تسميات الإعداد أو +متغيرات إعداد OAuth الخاصة بـ client-id/client-secret. -استخدم `channelEnvVars` في البيان عندما تكون للقناة مصادقة أو إعداد -مدفوع بالبيئة يجب أن تراه آليات التراجع العامة إلى shell-env أو فحوصات -الإعدادات/الحالة أو موجّهات الإعداد من دون تحميل وقت تشغيل القناة. +استخدم `channelEnvVars` في البيان عندما تمتلك القناة مصادقة أو إعدادًا +مدفوعًا بمتغيرات البيئة ينبغي لبدائل shell-env العامة أو فحوصات +الإعدادات/الحالة أو مطالبات الإعداد رؤيتها من دون تحميل وقت تشغيل القناة. ### ترتيب الخطافات واستخدامها -بالنسبة إلى إضافات النماذج/المزودين، يستدعي OpenClaw الخطافات بهذا الترتيب التقريبي. +بالنسبة إلى إضافات النماذج/المزوّدين، يستدعي OpenClaw الخطافات تقريبًا +بهذا الترتيب. ويمثل عمود "متى يُستخدم" دليل القرار السريع. -| # | الخطاف | ما الذي يفعله | متى يُستخدم | -| --- | --------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -| 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 عبر env-marker يملكه المزود؛ كما يملك `amazon-bedrock` هنا محلل env-marker مدمج خاصًا بـ AWS | -| 8 | `resolveSyntheticAuth` | إظهار مصادقة محلية/مستضافة ذاتيًا أو مدعومة بالإعدادات من دون حفظ نص واضح | عندما يمكن للمزود العمل مع علامة اعتماد اصطناعية/محلية | -| 9 | `resolveExternalAuthProfiles` | إضافة ملفات تعريف المصادقة الخارجية المملوكة للمزود؛ تكون قيمة `persistence` الافتراضية `runtime-only` لبيانات الاعتماد المملوكة لـ CLI/التطبيق | عندما يعيد المزود استخدام بيانات اعتماد خارجية من دون حفظ رموز تحديث منسوخة | -| 10 | `shouldDeferSyntheticProfileAuth` | خفض أولوية العناصر النائبة لملفات التعريف الاصطناعية المخزنة خلف المصادقة المدعومة بالبيئة/الإعدادات | عندما يخزن المزود ملفات تعريف اصطناعية نائبة يجب ألا تتقدم في الأولوية | -| 11 | `resolveDynamicModel` | تراجع متزامن لمعرفات النماذج المملوكة للمزود غير الموجودة بعد في السجل المحلي | عندما يقبل المزود معرفات نماذج upstream عشوائية | -| 12 | `prepareDynamicModel` | تهيئة غير متزامنة، ثم يُشغَّل `resolveDynamicModel` مرة أخرى | عندما يحتاج المزود إلى بيانات وصفية شبكية قبل حل المعرفات غير المعروفة | -| 13 | `normalizeResolvedModel` | إعادة كتابة نهائية قبل أن يستخدم المشغل المضمّن النموذج المحلول | عندما يحتاج المزود إلى إعادة كتابة للناقل لكنه لا يزال يستخدم ناقلًا أساسيًا | -| 14 | `contributeResolvedModelCompat` | الإسهام بأعلام توافق لنماذج المورد خلف ناقل متوافق آخر | عندما يتعرف المزود على نماذجه الخاصة على نواقل وكيلة من دون الاستيلاء على المزود | -| 15 | `capabilities` | بيانات وصفية خاصة بالمزود للنصوص/الأدوات تستخدمها منطق النواة المشتركة | عندما يحتاج المزود إلى خصائص خاصة بالنصوص أو بعائلة المزود | -| 16 | `normalizeToolSchemas` | تطبيع مخططات الأدوات قبل أن يراها المشغل المضمّن | عندما يحتاج المزود إلى تنظيف للمخططات على مستوى عائلة الناقل | -| 17 | `inspectToolSchemas` | إظهار تشخيصات مخططات يملكها المزود بعد التطبيع | عندما يريد المزود تحذيرات للكلمات المفتاحية من دون تعليم النواة قواعد خاصة بالمزود | -| 18 | `resolveReasoningOutputMode` | اختيار عقد مخرجات الاستدلال الأصلي أو الموسوم | عندما يحتاج المزود إلى استدلال موسوم/مخرجات نهائية بدل الحقول الأصلية | -| 19 | `prepareExtraParams` | تطبيع معلمات الطلب قبل مغلفات خيارات البث العامة | عندما يحتاج المزود إلى معلمات طلب افتراضية أو تنظيف معلمات خاص بكل مزود | -| 20 | `createStreamFn` | استبدال مسار البث العادي بالكامل بناقل مخصص | عندما يحتاج المزود إلى بروتوكول نقل مخصص، لا مجرد مغلف | -| 21 | `wrapStreamFn` | مغلف للبث بعد تطبيق المغلفات العامة | عندما يحتاج المزود إلى أغلفة توافق للرؤوس/الجسم/النموذج من دون ناقل مخصص | -| 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/etc | -| 29 | `isCacheTtlEligible` | سياسة ذاكرة التخزين المؤقت للموجّه للنواقل الوكيلة/الخلفية | عندما يحتاج المزود إلى بوابة TTL خاصة بالوكيل | -| 30 | `buildMissingAuthMessage` | بديل عن رسالة الاسترداد العامة عند غياب المصادقة | عندما يحتاج المزود إلى تلميح استرداد خاص بالمزود عند غياب المصادقة | -| 31 | `suppressBuiltInModel` | كبح النموذج القديم من upstream مع تلميح اختياري للمستخدم | عندما يحتاج المزود إلى إخفاء الصفوف القديمة من upstream أو استبدالها بتلميح مورّد | -| 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 يملكه المزود للذاكرة/البحث | عندما ينتمي سلوك embeddings للذاكرة إلى إضافة المزود | -| 41 | `buildReplayPolicy` | إرجاع سياسة replay تتحكم في معالجة النصوص الخاصة بالمزود | عندما يحتاج المزود إلى سياسة نصوص مخصصة (مثل إزالة كتل التفكير) | -| 42 | `sanitizeReplayHistory` | إعادة كتابة سجل replay بعد تنظيف النصوص العام | عندما يحتاج المزود إلى إعادة كتابة replay خاصة به تتجاوز مساعدات الضغط المشتركة | -| 43 | `validateReplayTurns` | التحقق النهائي من أدوار 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` | يحل مصادقة علامة البيئة لمزوّدي الإعدادات قبل تحميل مصادقة وقت التشغيل | عندما يملك المزوّد حلًا خاصًا به لمفتاح API بعلامة البيئة؛ كما يملك `amazon-bedrock` هنا أيضًا محللًا مضمّنًا لعلامات بيئة AWS | +| 8 | `resolveSyntheticAuth` | يكشف المصادقة المحلية/المستضافة ذاتيًا أو المعتمدة على الإعدادات من دون حفظ النص الصريح | عندما يمكن للمزوّد العمل مع علامة اعتماد تركيبية/محلية | +| 9 | `resolveExternalAuthProfiles` | يركّب ملفات تعريف المصادقة الخارجية المملوكة للمزوّد؛ القيمة الافتراضية لـ `persistence` هي `runtime-only` لبيانات الاعتماد المملوكة لـ CLI/التطبيق | عندما يعيد المزوّد استخدام بيانات اعتماد مصادقة خارجية من دون حفظ رموز تحديث منسوخة | +| 10 | `shouldDeferSyntheticProfileAuth` | يخفض أولوية العناصر النائبة لملفات التعريف التركيبية المخزّنة أمام المصادقة المعتمدة على البيئة/الإعدادات | عندما يخزّن المزوّد ملفات تعريف بعناصر نائبة تركيبية ينبغي ألا تتقدّم في الأولوية | +| 11 | `resolveDynamicModel` | تراجع متزامن لمعرّفات نماذج مملوكة للمزوّد غير موجودة بعد في السجل المحلي | عندما يقبل المزوّد معرّفات نماذج upstream عشوائية | +| 12 | `prepareDynamicModel` | تهيئة غير متزامنة، ثم يُعاد تشغيل `resolveDynamicModel` | عندما يحتاج المزوّد إلى بيانات وصفية من الشبكة قبل حل المعرّفات غير المعروفة | +| 13 | `normalizeResolvedModel` | إعادة كتابة نهائية قبل أن يستخدم العارض المضمّن النموذج الذي تم حله | عندما يحتاج المزوّد إلى إعادة كتابة النقل مع الاستمرار في استخدام نقل من النواة | +| 14 | `contributeResolvedModelCompat` | يساهم بأعلام توافق لنماذج المورّد الموجودة خلف نقل متوافق آخر | عندما يتعرف المزوّد على نماذجه الخاصة فوق نواقل proxy من دون أن يتولّى المزوّد نفسه | +| 15 | `capabilities` | بيانات وصفية خاصة بالمزوّد للنصوص/الأدوات تستخدمها منطق النواة المشترك | عندما يحتاج المزوّد إلى خصائص شاذة خاصة بالنصوص أو بعائلة المزوّد | +| 16 | `normalizeToolSchemas` | يطبّع مخططات الأدوات قبل أن يراها العارض المضمّن | عندما يحتاج المزوّد إلى تنظيف مخطط خاص بعائلة النقل | +| 17 | `inspectToolSchemas` | يكشف تشخيصات مخطط مملوكة للمزوّد بعد التطبيع | عندما يريد المزوّد تحذيرات للكلمات المفتاحية من دون تعليم النواة قواعد خاصة بالمزوّد | +| 18 | `resolveReasoningOutputMode` | يحدد عقد مخرجات الاستدلال الأصلي مقابل المعلَّم | عندما يحتاج المزوّد إلى مخرجات استدلال/نهائية معلَّمة بدلًا من الحقول الأصلية | +| 19 | `prepareExtraParams` | تطبيع معاملات الطلب قبل مغلفات خيارات البث العامة | عندما يحتاج المزوّد إلى معاملات طلب افتراضية أو تنظيف معاملات خاصًا بكل مزوّد | +| 20 | `createStreamFn` | يستبدل مسار البث العادي بالكامل بنقل مخصص | عندما يحتاج المزوّد إلى بروتوكول wire مخصص، وليس مجرد غلاف | +| 21 | `wrapStreamFn` | غلاف للبث بعد تطبيق الأغلفة العامة | عندما يحتاج المزوّد إلى أغلفة توافق للرؤوس/النص الأساسي/النموذج من دون نقل مخصص | +| 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` | سياسة cache للمزوّدين الذين يعملون كـ proxy/backhaul | عندما يحتاج المزوّد إلى تقييد TTL خاص بـ proxy | +| 30 | `buildMissingAuthMessage` | بديل للرسالة العامة الخاصة باستعادة المصادقة المفقودة | عندما يحتاج المزوّد إلى تلميح استعادة خاص به للمصادقة المفقودة | +| 31 | `suppressBuiltInModel` | إخفاء النماذج القديمة من upstream مع تلميح اختياري ظاهر للمستخدم | عندما يحتاج المزوّد إلى إخفاء صفوف upstream القديمة أو استبدالها بتلميح من المورّد | +| 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` | يبني مكيّف embedding مملوكًا للمزوّد من أجل الذاكرة/البحث | عندما ينتمي سلوك embedding الخاص بالذاكرة إلى إضافة المزوّد | +| 41 | `buildReplayPolicy` | يعيد سياسة إعادة تشغيل تتحكم في معالجة النصوص للمزوّد | عندما يحتاج المزوّد إلى سياسة نصوص مخصصة (على سبيل المثال، إزالة كتل التفكير) | +| 42 | `sanitizeReplayHistory` | يعيد كتابة سجل إعادة التشغيل بعد تنظيف النصوص العام | عندما يحتاج المزوّد إلى عمليات إعادة كتابة خاصة به لتاريخ إعادة التشغيل تتجاوز مساعدات الضغط المشتركة | +| 43 | `validateReplayTurns` | التحقق النهائي من أدوار إعادة التشغيل أو إعادة تشكيلها قبل العارض المضمّن | عندما يحتاج نقل المزوّد إلى تحقق أشد صرامة من الأدوار بعد التنقية العامة | +| 44 | `onModelSelected` | يشغّل آثارًا جانبية مملوكة للمزوّد بعد اختيار النموذج | عندما يحتاج المزوّد إلى telemetry أو حالة مملوكة له عندما يصبح نموذج ما نشطًا | يتحقق `normalizeModelId` و`normalizeTransport` و`normalizeConfig` أولًا من -إضافة المزود المطابقة، ثم ينتقل إلى إضافات مزود أخرى قادرة على الخطافات -حتى يغيّر أحدها فعليًا معرف النموذج أو الناقل/الإعدادات. وهذا يحافظ -على عمل الجسور المستعارة/المتوافقة من دون أن يحتاج المستدعي إلى معرفة -أي إضافة مجمعة تملك إعادة الكتابة. وإذا لم تُعد أي خطافة مزود كتابة -إدخال إعداد مدعوم من Google-family، فسيظل مطبّع إعدادات Google -المجمّع يطبّق تنظيف التوافق هذا. +إضافة المزوّد المطابقة، ثم ينتقل إلى إضافات المزوّد الأخرى القادرة على +الخطافات إلى أن يغيّر أحدها فعليًا معرّف النموذج أو النقل/الإعدادات. وهذا +يبقي طبقات alias/compat الخاصة بالمزوّد تعمل من دون الحاجة إلى أن يعرف +المستدعي أي إضافة مضمّنة تملك إعادة الكتابة. وإذا لم يُعِد أي خطاف مزوّد +كتابة إدخال إعدادات Google-family مدعوم، فسيظل مطبّع إعدادات Google +المضمّن يطبّق تنظيف التوافق هذا. -إذا احتاج المزود إلى بروتوكول نقل مخصص كامل أو منفذ طلبات مخصص، -فهذه فئة مختلفة من الامتدادات. هذه الخطافات مخصصة لسلوك المزود +إذا كان المزوّد يحتاج إلى بروتوكول wire مخصص بالكامل أو منفذ طلبات مخصص +بالكامل، فهذه فئة مختلفة من الامتداد. هذه الخطافات مخصّصة لسلوك المزوّد الذي لا يزال يعمل على حلقة الاستدلال العادية في OpenClaw. -### مثال على المزود +### مثال على مزوّد ```ts api.registerProvider({ @@ -778,125 +798,123 @@ api.registerProvider({ }); ``` -### أمثلة مدمجة +### أمثلة مضمّنة -- تستخدم 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 - من `openai-completions` إلى `openai-responses`, وتلميحات المصادقة - الواعية بـ Codex، وكبح Spark، وصفوف OpenAI الاصطناعية، وسياسة - التفكير/النموذج الحي لـ GPT-5؛ وتملك عائلة البث `openai-responses-defaults` - أغلفة OpenAI Responses الأصلية المشتركة لرؤوس الإسناد، - و`/fast`/`serviceTier`, وtext verbosity, وCodex web search الأصلي، - وتشكيل الحمولات المتوافقة مع الاستدلال، وإدارة سياق Responses. +- تستخدم Anthropic الخطافات `resolveDynamicModel` و`capabilities` و`buildAuthDoctorHint`، + و`resolveUsageAuth` و`fetchUsageSnapshot` و`isCacheTtlEligible`، + و`resolveDefaultThinkingLevel` و`applyConfigDefaults` و`isModernModelRef`، + و`wrapStreamFn` لأنها تملك التوافق الأمامي لـ Claude 4.6، وتلميحات + عائلة المزوّد، وإرشادات إصلاح المصادقة، وتكامل نقطة نهاية الاستخدام، + وأهلية cache الخاصة بالمطالبات، وإعدادات افتراضية واعية بالمصادقة، + وسياسة التفكير الافتراضي/التكيفية لـ Claude، وتشكيل البث الخاص بـ + Anthropic من أجل رؤوس beta، و`/fast` / `serviceTier`، و`context1m`. +- تبقى مساعدات البث الخاصة بـ Claude في Anthropic داخل الفجوة العامة + `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 المباشر من `openai-completions` إلى `openai-responses`، وتلميحات + المصادقة الواعية بـ Codex، وإخفاء Spark، وصفوف قوائم OpenAI التركيبية، + وسياسة التفكير/النماذج الحية لـ GPT-5؛ بينما تملك عائلة البث + `openai-responses-defaults` أغلفة OpenAI Responses الأصلية المشتركة + لرؤوس الإسناد، و`/fast`/`serviceTier`، وإسهاب النص، و`web search` الأصلية + لـ Codex، وتشكيل حمولة reasoning-compat، وإدارة سياق Responses. - تستخدم OpenRouter `catalog` بالإضافة إلى `resolveDynamicModel` و - `prepareDynamicModel` لأن المزود يمرر البيانات وقد يكشف معرفات - نماذج جديدة قبل تحديث الكتالوج الثابت في OpenClaw؛ كما يستخدم - `capabilities`, و`wrapStreamFn`, و`isCacheTtlEligible` لإبقاء - الرؤوس الخاصة بالمزود، وبيانات التوجيه الوصفية، وتصحيحات الاستدلال، - وسياسة ذاكرة التخزين المؤقت خارج النواة. تأتي سياسة replay الخاصة به من - عائلة `passthrough-gemini`, بينما تملك عائلة البث `openrouter-thinking` - حقن الاستدلال الوكيلي والتخطي للنماذج غير المدعومة / `auto`. -- تستخدم GitHub Copilot `catalog`, و`auth`, و`resolveDynamicModel`, و + `prepareDynamicModel` لأن المزوّد تمريري وقد يكشف معرّفات نماذج جديدة قبل + تحديث الكتالوج الثابت في OpenClaw؛ كما يستخدم `capabilities` و + `wrapStreamFn` و`isCacheTtlEligible` لإبقاء رؤوس الطلب الخاصة بالمزوّد، + والبيانات الوصفية للتوجيه، وترقيعات الاستدلال، وسياسة cache الخاصة + بالمطالبات خارج النواة. وتأتي سياسة إعادة التشغيل الخاصة به من عائلة + `passthrough-gemini`، بينما تملك عائلة البث `openrouter-thinking` حقن + الاستدلال عبر proxy وتجاوزات النماذج غير المدعومة / `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 عند التمهيد، - ووضع مخرجات الاستدلال الموسوم، ومطابقة النماذج الحديثة، بينما - تملك عائلة البث `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 فقط. + لأنه يحتاج إلى تسجيل دخول بالجهاز يملكه المزوّد، وسلوك تراجع للنموذج، + وخصائص شاذة في نصوص 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` لأن + عائلة إعادة التشغيل `google-gemini` تملك تراجع التوافق الأمامي لـ + Gemini 3.1، والتحقق الأصلي من إعادة تشغيل Gemini، وتنقية إعادة التشغيل + الابتدائية، ووضع مخرجات الاستدلال المعلَّم، ومطابقة النماذج الحديثة؛ + بينما تملك عائلة البث `google-thinking` تطبيع حمولة التفكير في Gemini؛ + كما يستخدم Gemini CLI OAuth أيضًا `formatApiKey` و`resolveUsageAuth` و + `fetchUsageSnapshot` لتنسيق الرموز، وتحليل الرموز، وربط نقطة نهاية الحصة. +- تستخدم Anthropic Vertex `buildReplayPolicy` عبر عائلة إعادة التشغيل + `anthropic-by-model` حتى يبقى تنظيف إعادة التشغيل الخاص بـ Claude + محصورًا بمعرّفات Claude بدلًا من كل نقل `anthropic-messages`. +- تستخدم Amazon Bedrock `buildReplayPolicy` و`matchesContextOverflowError` و + `classifyFailoverReason` و`resolveDefaultThinkingLevel` لأنها تملك تصنيف + أخطاء Bedrock الخاصة بالاختناق/عدم الجاهزية/تجاوز السياق لحركة + Anthropic-on-Bedrock؛ بينما تظل سياسة إعادة التشغيل الخاصة بها تشترك في + الحارس `anthropic-by-model` نفسه المخصص لـ Claude فقط. - تستخدم OpenRouter وKilocode وOpencode وOpencode Go - `buildReplayPolicy` من خلال عائلة replay `passthrough-gemini` - لأنها تمرر نماذج Gemini عبر نواقل متوافقة مع OpenAI وتحتاج إلى - تنقية thought-signature الخاصة بـ Gemini من دون تحقق replay أصلي - أو إعادة كتابة bootstrap. -- تستخدم MiniMax `buildReplayPolicy` من خلال - عائلة replay `hybrid-anthropic-openai` لأن مزودًا واحدًا يملك - دلالات Anthropic-message وOpenAI-compatible معًا؛ وتحافظ على - إسقاط كتل التفكير الخاصة بـ Claude على جانب Anthropic مع إعادة - تجاوز وضع مخرجات الاستدلال إلى الوضع الأصلي، بينما تملك عائلة البث - `minimax-fast-mode` إعادة كتابة نماذج fast-mode على مسار البث المشترك. -- تستخدم Moonshot `catalog` مع `wrapStreamFn` لأنها لا تزال تستخدم - ناقل OpenAI المشترك ولكنها تحتاج إلى تطبيع حمولات التفكير الذي - يملكه المزود؛ وتعيّن عائلة البث `moonshot-thinking` الإعدادات مع - حالة `/think` إلى حمولة التفكير الثنائي الأصلية الخاصة بها. -- تستخدم Kilocode `catalog`, و`capabilities`, و`wrapStreamFn`, و - `isCacheTtlEligible` لأنها تحتاج إلى رؤوس طلبات يملكها المزود، - وتطبيع حمولات الاستدلال، وتلميحات نصوص Gemini، وبوابة Anthropic - الخاصة بـ cache-TTL؛ وتحافظ عائلة البث `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` الخاص بهما مملوك للإضافة حتى لو كان الاستدلال لا يزال - يعمل عبر النواقل المشتركة. + `buildReplayPolicy` عبر عائلة إعادة التشغيل `passthrough-gemini` لأنها + تمرر نماذج Gemini عبر نواقل متوافقة مع OpenAI وتحتاج إلى تنقية + thought-signature الخاصة بـ Gemini من دون تحقق أصلي من إعادة تشغيل Gemini + أو إعادة كتابة ابتدائية. +- تستخدم MiniMax `buildReplayPolicy` عبر عائلة إعادة التشغيل + `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 + cache؛ وتحافظ عائلة البث `kilocode-thinking` على حقن تفكير Kilo في مسار + البث المشترك عبر proxy مع تجاوز `kilo/auto` ومعرّفات نماذج proxy الأخرى + التي لا تدعم حمولات الاستدلال الصريحة. +- تستخدم 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 المتوافق أماميًا، وتصحيحات التوافق المملوكة + للمزوّد مثل ملف tool-schema الخاص بـ 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` الخاص بهما مملوك للإضافة حتى مع استمرار تشغيل الاستدلال + عبر النواقل المشتركة. ## مساعدات وقت التشغيل -يمكن للإضافات الوصول إلى مساعدين مختارين من النواة عبر `api.runtime`. بالنسبة إلى TTS: +يمكن للإضافات الوصول إلى مجموعة محددة من مساعدات النواة عبر `api.runtime`. +وبالنسبة إلى TTS: ```ts const clip = await api.runtime.tts.textToSpeech({ @@ -917,14 +935,19 @@ const voices = await api.runtime.tts.listVoices({ ملاحظات: -- يعيد `textToSpeech` حمولة خرج TTS الأساسية العادية لأسطح الملفات/الملاحظات الصوتية. -- يستخدم إعداد `messages.tts` الأساسي واختيار المزود. -- يعيد مخزن صوت PCM المؤقت + معدل العينة. ويجب على الإضافات إعادة أخذ العينات/الترميز من أجل المزودين. -- `listVoices` اختياري لكل مزود. استخدمه لمنتقيات الأصوات أو تدفقات الإعداد المملوكة للمورد. -- قد تتضمن قوائم الأصوات بيانات وصفية أغنى مثل اللغة والمنطقة والنوع وعلامات الشخصية لمنتقيات تراعي المزود. -- يدعم OpenAI وElevenLabs الاتصالات الهاتفية اليوم. ولا يدعم Microsoft ذلك. +- تعيد `textToSpeech` حمولة مخرجات TTS العادية في النواة لأسطح + الملفات/الملاحظات الصوتية. +- تستخدم إعدادات `messages.tts` في النواة واختيار المزوّد. +- تعيد مخزن PCM الصوتي المؤقت + معدل العيّنة. وعلى الإضافات إعادة + أخذ العينات/الترميز للمزوّدين. +- `listVoices` اختيارية بحسب المزوّد. استخدمها لمنتقيات الأصوات أو تدفقات + الإعداد المملوكة للمورّد. +- يمكن أن تتضمن قوائم الأصوات بيانات وصفية أغنى مثل locale وgender + وعلامات الشخصية لمنتقيات واعية بالمزوّد. +- يدعم OpenAI وElevenLabs الهاتف حاليًا. أما Microsoft فلا يدعمه. -يمكن للإضافات أيضًا تسجيل مزودي الكلام عبر `api.registerSpeechProvider(...)`. +يمكن للإضافات أيضًا تسجيل مزوّدي الكلام عبر +`api.registerSpeechProvider(...)`. ```ts api.registerSpeechProvider({ @@ -944,15 +967,16 @@ api.registerSpeechProvider({ ملاحظات: -- أبقِ سياسة TTS وآلية التراجع وتسليم الردود في النواة. -- استخدم مزودي الكلام لسلوك التوليف المملوك للمورد. -- يُطبَّع الإدخال القديم `edge` الخاص بـ Microsoft إلى معرّف المزود `microsoft`. -- نموذج الملكية المفضل موجَّه حسب الشركة: يمكن لإضافة مورد واحدة أن تملك - مزودي النص والكلام والصور والوسائط المستقبلية مع إضافة OpenClaw - لعقود تلك القدرات. +- أبقِ سياسة TTS وآليات التراجع وتسليم الردود في النواة. +- استخدم مزوّدي الكلام لسلوك التركيب المملوك للمورّد. +- يُطبَّع الإدخال القديم `edge` الخاص بـ Microsoft إلى معرّف المزوّد + `microsoft`. +- نموذج الملكية المفضّل موجه نحو الشركة: يمكن لإضافة مورّد واحدة أن تملك + النص، والكلام، والصورة، ومزوّدي الوسائط مستقبلًا مع إضافة OpenClaw + لعقود تلك الإمكانات. -أما بالنسبة إلى فهم الصور/الصوت/الفيديو، فتسجل الإضافات مزودًا واحدًا مكتوب -الأنواع لفهم الوسائط بدل حقيبة عامة من المفاتيح/القيم: +بالنسبة إلى فهم الصور/الصوت/الفيديو، تسجّل الإضافات مزوّد +media-understanding مكتوبًا واحدًا بدلًا من حقيبة مفتاح/قيمة عامة: ```ts api.registerMediaUnderstandingProvider({ @@ -966,16 +990,17 @@ api.registerMediaUnderstandingProvider({ ملاحظات: -- أبقِ التنسيق وآلية التراجع والإعدادات وربط القنوات في النواة. -- أبقِ سلوك المورد في إضافة المزود. -- يجب أن يبقى التوسع الإضافي مكتوب الأنواع: أساليب اختيارية جديدة، وحقول - نتائج اختيارية جديدة، وقدرات اختيارية جديدة. -- يتبع توليد الفيديو النمط نفسه بالفعل: - - تملك النواة عقد القدرة ومساعد وقت التشغيل - - تسجل إضافات المورد `api.registerVideoGenerationProvider(...)` +- أبقِ التنسيق، وآليات التراجع، والإعدادات، وربط القنوات في النواة. +- أبقِ سلوك المورّد داخل إضافة المزوّد. +- يجب أن يبقى التوسع الإضافي مكتوبًا Typed: أساليب اختيارية جديدة، وحقول + نتائج اختيارية جديدة، وإمكانات اختيارية جديدة. +- يتبع توليد الفيديو بالفعل النمط نفسه: + - تملك النواة عقد الإمكانية ومساعد وقت التشغيل + - تسجّل إضافات المورّدين `api.registerVideoGenerationProvider(...)` - تستهلك إضافات الميزات/القنوات `api.runtime.videoGeneration.*` -بالنسبة إلى مساعدات وقت التشغيل الخاصة بفهم الوسائط، يمكن للإضافات استدعاء: +وبالنسبة إلى مساعدات وقت التشغيل الخاصة بـ media-understanding، يمكن +للإضافات استدعاء: ```ts const image = await api.runtime.mediaUnderstanding.describeImageFile({ @@ -990,27 +1015,30 @@ const video = await api.runtime.mediaUnderstanding.describeVideoFile({ }); ``` -وبالنسبة إلى نسخ الصوت، يمكن للإضافات استخدام وقت تشغيل فهم الوسائط أو -الاسم المستعار الأقدم لـ STT: +وبالنسبة إلى نسخ الصوت، يمكن للإضافات استخدام وقت تشغيل +media-understanding أو الاسم البديل الأقدم STT: ```ts const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ filePath: "/tmp/inbound-audio.ogg", cfg: api.config, - // اختياري عندما لا يمكن استنتاج MIME بشكل موثوق: + // Optional when MIME cannot be inferred reliably: mime: "audio/ogg", }); ``` ملاحظات: -- `api.runtime.mediaUnderstanding.*` هو السطح المشترك المفضل - لفهم الصور/الصوت/الفيديو. -- يستخدم إعداد الصوت الأساسي لفهم الوسائط (`tools.media.audio`) وترتيب التراجع بين المزودين. -- يعيد `{ text: undefined }` عندما لا ينتج أي خرج نسخ (على سبيل المثال، عندما يكون الإدخال متخطيًا/غير مدعوم). -- لا يزال `api.runtime.stt.transcribeAudioFile(...)` اسمًا مستعارًا للتوافق. +- `api.runtime.mediaUnderstanding.*` هو السطح المشترك المفضل لفهم + الصور/الصوت/الفيديو. +- يستخدم إعدادات الصوت الخاصة بـ media-understanding في النواة + (`tools.media.audio`) وترتيب التراجع الخاص بالمزوّد. +- يعيد `{ text: undefined }` عندما لا يتم إنتاج مخرجات نسخ + (على سبيل المثال، عند تخطي الإدخال أو عدم دعمه). +- يبقى `api.runtime.stt.transcribeAudioFile(...)` اسمًا بديلًا للتوافق. -يمكن للإضافات أيضًا تشغيل عمليات وكيل فرعي في الخلفية عبر `api.runtime.subagent`: +يمكن للإضافات أيضًا إطلاق تشغيلات subagent في الخلفية عبر +`api.runtime.subagent`: ```ts const result = await api.runtime.subagent.run({ @@ -1024,16 +1052,19 @@ const result = await api.runtime.subagent.run({ ملاحظات: -- `provider` و`model` تجاوزات اختيارية لكل تشغيل، وليسا تغييرات دائمة للجلسة. -- لا يلتزم OpenClaw بحقول التجاوز هذه إلا للمتصلين الموثوقين. -- بالنسبة إلى التشغيلات الاحتياطية المملوكة للإضافة، يجب على المشغلين تفعيل - `plugins.entries..subagent.allowModelOverride: true`. -- استخدم `plugins.entries..subagent.allowedModels` لتقييد الإضافات الموثوقة - إلى أهداف `provider/model` معيارية محددة، أو `"*"` للسماح الصريح بأي هدف. -- تظل تشغيلات الوكلاء الفرعيين للإضافات غير الموثوقة تعمل، لكن تُرفض طلبات التجاوز بدل أن تتراجع بصمت. +- `provider` و`model` هما تجاوزات اختيارية لكل تشغيل، وليسا تغييرات دائمة + للجلسة. +- لا يحترم OpenClaw حقول التجاوز هذه إلا للجهات الموثوقة. +- بالنسبة إلى تشغيلات التراجع المملوكة للإضافة، يجب على المشغّلين تفعيل + ذلك صراحةً عبر `plugins.entries..subagent.allowModelOverride: true`. +- استخدم `plugins.entries..subagent.allowedModels` لتقييد الإضافات + الموثوقة بأهداف `provider/model` قانونية محددة، أو `"*"` للسماح صراحةً + بأي هدف. +- تظل تشغيلات subagent الخاصة بالإضافات غير الموثوقة تعمل، لكن تُرفَض طلبات + التجاوز بدلًا من التراجع الصامت. -بالنسبة إلى البحث في الويب، يمكن للإضافات استهلاك مساعد وقت التشغيل المشترك بدلًا من -الوصول مباشرة إلى ربط أداة الوكيل: +وبالنسبة إلى البحث في الويب، يمكن للإضافات استهلاك مساعد وقت التشغيل +المشترك بدلًا من الوصول إلى ربط أداة الوكيل: ```ts const providers = api.runtime.webSearch.listProviders({ @@ -1049,14 +1080,16 @@ const result = await api.runtime.webSearch.search({ }); ``` -يمكن للإضافات أيضًا تسجيل مزودي البحث في الويب عبر +يمكن للإضافات أيضًا تسجيل مزوّدي البحث في الويب عبر `api.registerWebSearchProvider(...)`. ملاحظات: -- أبقِ اختيار المزود وحل بيانات الاعتماد ودلالات الطلب المشتركة في النواة. -- استخدم مزودي البحث في الويب لنواقل البحث الخاصة بالمورد. -- `api.runtime.webSearch.*` هو السطح المشترك المفضل لإضافات الميزات/القنوات التي تحتاج إلى سلوك بحث من دون الاعتماد على مغلف أداة الوكيل. +- أبقِ اختيار المزوّد، وحل بيانات الاعتماد، ودلالات الطلب المشتركة في + النواة. +- استخدم مزوّدي البحث في الويب لوسائط النقل الخاصة بالمورّد. +- `api.runtime.webSearch.*` هو السطح المشترك المفضل لإضافات الميزات/القنوات + التي تحتاج إلى سلوك البحث من دون الاعتماد على غلاف أداة الوكيل. ### `api.runtime.imageGeneration` @@ -1071,8 +1104,8 @@ const providers = api.runtime.imageGeneration.listProviders({ }); ``` -- `generate(...)`: أنشئ صورة باستخدام سلسلة مزودي توليد الصور المهيأة. -- `listProviders(...)`: اعرض مزودي توليد الصور المتاحين وقدراتهم. +- `generate(...)`: يولّد صورة باستخدام سلسلة مزوّدي توليد الصور المهيأة. +- `listProviders(...)`: يسرد مزوّدي توليد الصور المتاحين وإمكاناتهم. ## مسارات Gateway HTTP @@ -1093,263 +1126,295 @@ api.registerHttpRoute({ حقول المسار: -- `path`: مسار الطريق ضمن خادم HTTP الخاص بـ Gateway. -- `auth`: مطلوب. استخدم `"gateway"` لطلب مصادقة البوابة العادية، أو `"plugin"` للمصادقة/التحقق الخاص بالإضافة أو webhook. +- `path`: مسار route ضمن خادم Gateway HTTP. +- `auth`: مطلوب. استخدم `"gateway"` لفرض مصادقة Gateway العادية، أو + `"plugin"` للمصادقة/التحقق من webhook الذي تديره الإضافة. - `match`: اختياري. `"exact"` (الافتراضي) أو `"prefix"`. -- `replaceExisting`: اختياري. يسمح للإضافة نفسها باستبدال تسجيل مسار سابق خاص بها. -- `handler`: أرجع `true` عندما يكون المسار قد عالج الطلب. +- `replaceExisting`: اختياري. يسمح للإضافة نفسها باستبدال تسجيل المسار + الحالي الخاص بها. +- `handler`: أعد `true` عندما يكون المسار قد عالج الطلب. ملاحظات: -- تمت إزالة `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"` على ingress خاص) لا تكرم `x-openclaw-scopes` إلا عندما يكون الرأس حاضرًا صراحة - - إذا كان `x-openclaw-scopes` غائبًا في طلبات مسارات الإضافات الحاملة للهوية، يتراجع نطاق وقت التشغيل إلى `operator.write` -- القاعدة العملية: لا تفترض أن مسار إضافة بمصادقة البوابة هو سطح إدارة ضمني. وإذا كان مسارك يحتاج إلى سلوك إداري فقط، فاطلب وضع مصادقة يحمل هوية ووثّق عقد الرأس الصريح `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` الصريح. -## مسارات استيراد SDK الخاصة بالإضافات +## مسارات استيراد Plugin SDK -استخدم المسارات الفرعية لـ SDK بدل استيراد `openclaw/plugin-sdk` الأحادي عند -تأليف الإضافات: +استخدم المسارات الفرعية لـ SDK بدلًا من الاستيراد الأحادي +`openclaw/plugin-sdk` عند تأليف الإضافات: -- `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` الموطن المشترك لإزالة - الارتداد، ومطابقة الإشارات، ومساعدات سياسة الإشارة الواردة، وتنسيق - المغلفات الواردة، ومساعدات سياق المغلف الوارد. - ويمثل `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/التسجيل، بما في ذلك +- `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` لربط الإعداد/المصادقة/الرد/الويب هوك + المشترك. ويُعد `channel-inbound` الموطن المشترك لإلغاء الارتداد debounce، + ومطابقة الإشارات mention، ومساعدات سياسة الإشارات الواردة، وتنسيق + المغلفات، ومساعدات سياق المغلفات الواردة. + ويمثل `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` هي مدخل الإضافة المجمعة، + الإخفاء، ومساعدات directive-tag، وأدوات النص الآمن. +- يجب أن تفضّل الفجوات الخاصة بالموافقات في القنوات عقد + `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`. + `wrapAnthropicProviderStream`، ومساعدات رؤوس beta، وتحليل + `service_tier`. + - تستخدم OpenAI `api.js` لبُنّاة المزوّدين، ومساعدات النماذج الافتراضية، + وبُنّاة مزوّدي الوقت الفعلي. + - تستخدم OpenRouter `api.js` لباني المزوّد الخاص بها بالإضافة إلى + مساعدات الإعداد/التهيئة، بينما يمكن لـ `register.runtime.js` أن يعيد + تصدير مساعدات `plugin-sdk/provider-stream` العامة للاستخدام المحلي داخل + المستودع. +- تفضّل نقاط الدخول العامة المحمّلة عبر الواجهة snapshot إعدادات وقت + التشغيل النشط عند وجوده، ثم تتراجع إلى ملف الإعدادات المحلول على القرص + عندما لا يكون OpenClaw قد بدأ بعد في تقديم snapshot وقت تشغيل. +- تظل الأساسيات العامة المشتركة هي عقد SDK العام المفضل. ولا تزال توجد + مجموعة توافق صغيرة محجوزة من فجوات المساعدة المسماة بأسماء قنوات مضمّنة. + تعامل مع هذه على أنها فجوات صيانة/توافق للإضافات المضمّنة، لا أهداف + استيراد جديدة لطرف ثالث؛ ويجب أن تستمر العقود الجديدة العابرة للقنوات في + الوصول إلى المسارات الفرعية العامة `plugin-sdk/*` أو إلى الحاويات + المحلية للإضافة `api.js` / `runtime-api.js`. ملاحظة التوافق: -- تجنب الحاوية الجذرية `openclaw/plugin-sdk` في الشيفرة الجديدة. -- فضّل أولًا الأساسيات المستقرة الضيقة. فالمسارات الفرعية الأحدث الخاصة بالإعداد/الاقتران/الرد/ - والملاحظات/العقد/الوارد/الخيوط/الأوامر/الإدخال السري/webhook/البنية/ - وقائمة السماح/الحالة/أداة الرسائل هي العقد المقصود لعمل الإضافات الجديدة - المجمعة والخارجية. - ويجب أن يكون التحليل/المطابقة الخاصة بالأهداف على `openclaw/plugin-sdk/channel-targets`. - وتجب أن تكون بوابات إجراءات الرسائل ومساعدات معرفات رسائل التفاعل على +- تجنّب الحاوية الجذرية `openclaw/plugin-sdk` في الشيفرة الجديدة. +- فضّل أولًا الأساسيات المستقرة الضيقة. فالمسارات الفرعية الأحدث الخاصة بـ + setup/pairing/reply/feedback/contract/inbound/threading/command/secret-input/webhook/infra/ + allowlist/status/message-tool هي العقد المقصود لأعمال الإضافات المضمّنة + والخارجية الجديدة. + وينتمي تحليل/مطابقة الأهداف إلى `openclaw/plugin-sdk/channel-targets`. + كما تنتمي بوابات إجراءات الرسائل ومساعدات معرّف رسالة التفاعل إلى `openclaw/plugin-sdk/channel-actions`. -- لا تكون الحاويات المساعدة الخاصة بالامتدادات المجمعة مستقرة افتراضيًا. وإذا - كانت المساعدة مطلوبة فقط لامتداد مجمع، فابقها خلف وصلة - `api.js` أو `runtime-api.js` المحلية الخاصة به بدل ترقيتها إلى +- لا تُعد حاويات المساعدة الخاصة بالامتدادات المضمّنة مستقرة افتراضيًا. إذا + كانت هناك مساعدة يحتاج إليها امتداد مضمّن فقط، فأبقها خلف الفجوة المحلية + `api.js` أو `runtime-api.js` الخاصة بالامتداد بدلًا من ترقيتها إلى `openclaw/plugin-sdk/`. -- يجب أن تكون وصلات المساعدات المشتركة الجديدة عامة لا ممهورة باسم قناة. - فتحليل الأهداف المشتركة ينتمي إلى `openclaw/plugin-sdk/channel-targets`; - أما الأجزاء الداخلية الخاصة بالقناة فتبقى خلف `api.js` أو `runtime-api.js` - المحلية الخاصة بالإضافة المالكة. -- توجد مسارات فرعية خاصة بالقدرات مثل `image-generation`, - و`media-understanding`, و`speech` لأن الإضافات المجمعة/الأصلية تستخدمها - اليوم. لكن وجودها لا يعني بحد ذاته أن كل مساعد مُصدَّر يمثل - عقدًا خارجيًا طويل الأمد ومجمّدًا. +- ينبغي أن تكون فجوات المساعدة المشتركة الجديدة عامة، لا ممهورة باسم + قناة. وينتمي تحليل الأهداف المشترك إلى + `openclaw/plugin-sdk/channel-targets`؛ بينما تبقى الواجهات الداخلية + الخاصة بالقناة خلف الفجوة المحلية `api.js` أو `runtime-api.js` الخاصة + بالإضافة المالكة. +- توجد مسارات فرعية خاصة بالإمكانات مثل `image-generation` و + `media-understanding` و`speech` لأن الإضافات المضمّنة/الأصلية تستخدمها + اليوم. ووجودها لا يعني بحد ذاته أن كل مساعد مصدَّر هو عقد خارجي ثابت على + المدى الطويل. ## مخططات أداة الرسائل -يجب أن تملك الإضافات المساهمات الخاصة بالقناة في مخطط -`describeMessageTool(...)`. أبقِ الحقول الخاصة بالمزود داخل الإضافة، -لا في النواة المشتركة. +ينبغي أن تملك الإضافات مساهمات المخطط الخاصة بالقناة في +`describeMessageTool(...)`. أبقِ الحقول الخاصة بالمورّد داخل الإضافة، لا في +النواة المشتركة. -وبالنسبة إلى أجزاء المخطط المحمولة المشتركة، أعد استخدام المساعدات العامة المصدَّرة عبر -`openclaw/plugin-sdk/channel-actions`: +وبالنسبة إلى أجزاء المخطط المشتركة القابلة للنقل، أعد استخدام المساعدات +العامة المصدَّرة عبر `openclaw/plugin-sdk/channel-actions`: -- `createMessageToolButtonsSchema()` لحمولات على نمط شبكة الأزرار +- `createMessageToolButtonsSchema()` لحمولات نمط شبكة الأزرار - `createMessageToolCardSchema()` لحمولات البطاقات المنظمة -إذا كان شكل المخطط منطقيًا لمزود واحد فقط، فعرّفه في مصدر تلك الإضافة -الخاص بدل ترقيته إلى SDK المشترك. +إذا كان شكل مخطط ما منطقيًا لمورّد واحد فقط، فعرّفه في المصدر الخاص بتلك +الإضافة بدلًا من ترقيته إلى SDK المشترك. ## حل أهداف القنوات -يجب أن تملك إضافات القنوات دلالات الأهداف الخاصة بالقناة. أبقِ مضيف -الإرسال الخارجي عامًا واستخدم سطح محول المراسلة لقواعد المزود: +ينبغي أن تملك إضافات القنوات دلالات الأهداف الخاصة بالقناة. أبقِ مضيف +الإرسال الخارجي مشتركًا وعامًا، واستخدم سطح مكيّف المراسلة لقواعد المورّد: -- `messaging.inferTargetChatType({ to })` يقرر ما إذا كان يجب التعامل مع - هدف مُطبَّع على أنه `direct` أو `group` أو `channel` قبل البحث في الدليل. -- `messaging.targetResolver.looksLikeId(raw, normalized)` يخبر النواة ما إذا كان - يجب أن يتجاوز الإدخال مباشرةً إلى حل شبيه بالمعرف بدل البحث في الدليل. -- `messaging.targetResolver.resolveTarget(...)` هو تراجع الإضافة عندما - تحتاج النواة إلى حل نهائي يملكه المزود بعد التطبيع أو بعد عدم العثور عليه في الدليل. -- `messaging.resolveOutboundSessionRoute(...)` يملك إنشاء مسار الجلسة الصادر الخاص بالمزود بمجرد حل الهدف. +- يقرر `messaging.inferTargetChatType({ to })` ما إذا كان ينبغي التعامل مع + هدف مطبّع على أنه `direct` أو `group` أو `channel` قبل البحث في الدليل. +- يحدّد `messaging.targetResolver.looksLikeId(raw, normalized)` ما إذا كان + ينبغي للنواة أن تتجاوز مباشرةً إلى الحل الشبيه بالمعرّف بدلًا من البحث + في الدليل. +- يمثّل `messaging.targetResolver.resolveTarget(...)` مسار التراجع الخاص + بالإضافة عندما تحتاج النواة إلى حل نهائي يملكه المورّد بعد التطبيع أو + بعد الإخفاق في الدليل. +- يملك `messaging.resolveOutboundSessionRoute(...)` إنشاء مسار الجلسة + الخارجة الخاص بالمورّد بعد حل الهدف. التقسيم الموصى به: -- استخدم `inferTargetChatType` لقرارات الفئة التي يجب أن تحدث قبل - البحث عن الأقران/المجموعات. -- استخدم `looksLikeId` للتحقق من "اعتبر هذا معرف هدف صريحًا/أصليًا". -- استخدم `resolveTarget` للتراجع الخاص بالمزود في التطبيع، لا للبحث الواسع في الدليل. -- أبقِ المعرفات الأصلية للمزود مثل معرفات الدردشة، ومعرفات الخيوط، وJIDs، والمعالِجات، ومعرفات الغرف - داخل قيم `target` أو في معلمات خاصة بالمزود، لا في حقول SDK عامة. +- استخدم `inferTargetChatType` لقرارات التصنيف التي ينبغي أن تحدث قبل + البحث في الأقران/المجموعات. +- استخدم `looksLikeId` لفحوص "تعامل مع هذا كمعرّف هدف صريح/أصلي". +- استخدم `resolveTarget` لتراجع التطبيع الخاص بالمورّد، لا للبحث الواسع في + الدليل. +- أبقِ المعرّفات الأصلية الخاصة بالمورّد مثل chat ids وthread ids وJIDs + وhandles وroom ids داخل قيم `target` أو داخل معاملات خاصة بالمورّد، لا + في حقول SDK العامة. -## الأدلة المدعومة بالإعدادات +## الأدلة المعتمدة على الإعدادات -يجب على الإضافات التي تستمد إدخالات الدليل من الإعدادات أن تُبقي هذا المنطق داخل -الإضافة وأن تعيد استخدام المساعدات المشتركة من +ينبغي أن تُبقي الإضافات التي تشتق إدخالات الدليل من الإعدادات هذا المنطق +داخل الإضافة وأن تعيد استخدام المساعدات المشتركة من `openclaw/plugin-sdk/directory-runtime`. -استخدم ذلك عندما تحتاج القناة إلى أقران/مجموعات مدعومة بالإعدادات مثل: +استخدم هذا عندما تحتاج قناة إلى أقران/مجموعات مدعومة بالإعدادات مثل: -- أقران الرسائل المباشرة المعتمدين على قائمة السماح -- خرائط القنوات/المجموعات المضبوطة -- تراجعات الدليل الثابتة المرتبطة بالحساب +- أقران الرسائل المباشرة المعتمدين على allowlist +- خرائط القنوات/المجموعات المهيأة +- بدائل الدليل الثابتة المقيّدة بالحساب -المساعدات المشتركة في `directory-runtime` تعالج العمليات العامة فقط: +لا تتولى المساعدات المشتركة في `directory-runtime` إلا العمليات العامة: -- تصفية الاستعلام +- تصفية الاستعلامات - تطبيق الحدود -- إزالة التكرار/التطبيع +- مساعدات إزالة التكرار/التطبيع - بناء `ChannelDirectoryEntry[]` -أما فحص الحسابات الخاص بالقناة وتطبيع المعرفات فيجب أن يبقيا داخل تنفيذ الإضافة. +وينبغي أن يظل فحص الحساب الخاص بالقناة وتطبيع المعرّفات داخل تنفيذ +الإضافة. -## كتالوجات المزودين +## كتالوجات المزوّدين -يمكن لإضافات المزودين تعريف كتالوجات نماذج للاستدلال باستخدام +يمكن لإضافات المزوّدين تعريف كتالوجات نماذج للاستدلال باستخدام `registerProvider({ catalog: { run(...) { ... } } })`. -تعيد `catalog.run(...)` الشكل نفسه الذي يكتبه OpenClaw في +يعيد `catalog.run(...)` الشكل نفسه الذي يكتبه OpenClaw في `models.providers`: -- `{ provider }` لإدخال مزود واحد -- `{ providers }` لعدة إدخالات مزود +- `{ provider }` لإدخال مزوّد واحد +- `{ providers }` لعدة إدخالات مزوّدين -استخدم `catalog` عندما تملك الإضافة معرفات النماذج الخاصة بالمزود أو -إعدادات base URL الافتراضية أو البيانات الوصفية للنماذج المحكومة بالمصادقة. +استخدم `catalog` عندما تملك الإضافة معرّفات نماذج خاصة بالمزوّد، أو +إعدادات افتراضية لـ base URL، أو بيانات وصفية للنماذج محكومة بالمصادقة. -يتحكم `catalog.order` في وقت دمج كتالوج الإضافة نسبة إلى المزودين -الضمنيين المدمجين في OpenClaw: +يتحكم `catalog.order` في توقيت دمج كتالوج الإضافة مقارنةً بمزوّدي OpenClaw +الضمنيين المضمّنين: -- `simple`: مزودون عاديون يعتمدون على مفتاح API أو البيئة -- `profile`: مزودون يظهرون عند وجود ملفات تعريف المصادقة -- `paired`: مزودون يركّبون عدة إدخالات مزود مترابطة -- `late`: المرور الأخير، بعد المزودين الضمنيين الآخرين +- `simple`: مزوّدون عاديون يعتمدون على API-key أو متغيرات البيئة +- `profile`: مزوّدون يظهرون عند وجود ملفات تعريف للمصادقة +- `paired`: مزوّدون يركّبون عدة إدخالات مزوّدين مترابطة +- `late`: المرور الأخير، بعد المزوّدين الضمنيين الآخرين -يفوز المزود اللاحق عند تعارض المفتاح، وبالتالي يمكن للإضافات عمدًا تجاوز -إدخال مزود مدمج يحمل معرّف المزود نفسه. +يربح المزوّد اللاحق عند تعارض المفاتيح، لذلك يمكن للإضافات أن تتعمد تجاوز +إدخال مزوّد مضمّن له معرّف المزوّد نفسه. التوافق: -- لا يزال `discovery` يعمل كاسم مستعار قديم -- إذا سُجِّل كل من `catalog` و`discovery`، فسيستخدم OpenClaw `catalog` +- لا يزال `discovery` يعمل كاسم بديل قديم +- إذا سُجّل كل من `catalog` و`discovery`، يستخدم OpenClaw `catalog` ## فحص القنوات للقراءة فقط -إذا كانت إضافتك تسجل قناة، ففضّل تنفيذ +إذا كانت إضافتك تسجّل قناة، فافضّل تنفيذ `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 يجب ألا تحتاج إلى + تجسيد بيانات اعتماد وقت التشغيل لمجرد وصف الإعداد. السلوك الموصى به لـ `inspectAccount(...)`: -- أعد فقط حالة حساب وصفية. -- حافظ على `enabled` و`configured`. -- ضمّن حقول مصدر/حالة بيانات الاعتماد عند الحاجة، مثل: +- أعد حالة وصفية للحساب فقط. +- احتفظ بـ `enabled` و`configured`. +- ضمّن حقول مصدر/حالة بيانات الاعتماد عند الصلة، مثل: - `tokenSource`, `tokenStatus` - `botTokenSource`, `botTokenStatus` - `appTokenSource`, `appTokenStatus` - `signingSecretSource`, `signingSecretStatus` -- لا تحتاج إلى إرجاع قيم الرموز الخام فقط للإبلاغ عن التوفر للقراءة فقط. - يكفي إرجاع `tokenStatus: "available"` (وحقل المصدر المطابق). -- استخدم `configured_unavailable` عندما تكون بيانات الاعتماد مضبوطة عبر SecretRef ولكن - غير متاحة في مسار الأمر الحالي. +- لا تحتاج إلى إعادة قيم الرموز الخام لمجرد الإبلاغ عن التوافر للقراءة فقط. + فإعادة `tokenStatus: "available"` (وحقل المصدر المطابق) كافية لأوامر + نمط الحالة. +- استخدم `configured_unavailable` عندما تكون بيانات الاعتماد مهيأة عبر + SecretRef لكنها غير متاحة في مسار الأمر الحالي. -وهذا يسمح للأوامر المخصصة للقراءة فقط بالإبلاغ عن "مهيأ لكنه غير متاح في مسار -الأمر هذا" بدل التعطل أو الإبلاغ خطأً عن أن الحساب غير مهيأ. +يتيح ذلك لأوامر القراءة فقط الإبلاغ عن "مهيأ لكنه غير متاح في مسار الأمر +هذا" بدلًا من التعطل أو الإبلاغ الخاطئ عن أن الحساب غير مهيأ. -## حزم Package packs +## حِزم الحزم -يمكن أن يضم دليل الإضافة `package.json` مع `openclaw.extensions`: +يمكن أن يتضمن دليل الإضافة `package.json` يحتوي على +`openclaw.extensions`: ```json { @@ -1361,64 +1426,68 @@ api.registerHttpRoute({ } ``` -يصبح كل إدخال إضافة. وإذا أدرجت الحزمة عدة امتدادات، يصبح معرّف الإضافة +يصبح كل إدخال إضافة. وإذا سردت الحزمة عدة امتدادات، يصبح معرّف الإضافة `name/`. إذا كانت إضافتك تستورد تبعيات npm، فثبّتها في ذلك الدليل بحيث يكون `node_modules` متاحًا (`npm install` / `pnpm install`). -حاجز أمان: يجب أن يبقى كل إدخال في `openclaw.extensions` داخل دليل الإضافة -بعد حل الروابط الرمزية. وتُرفض الإدخالات التي تفلت من دليل الحزمة. +حاجز أمان: يجب أن يبقى كل إدخال في `openclaw.extensions` داخل دليل +الإضافة بعد حل الروابط الرمزية. وتُرفَض الإدخالات التي تفلت من دليل +الحزمة. -ملاحظة أمان: يثبت `openclaw plugins install` تبعيات الإضافات باستخدام -`npm install --omit=dev --ignore-scripts` (من دون نصوص lifecycle، ومن دون تبعيات تطوير وقت التشغيل). حافظ على أشجار -تبعيات الإضافة "JS/TS خالصة" وتجنب الحزم التي تتطلب عمليات بناء `postinstall`. +ملاحظة أمنية: يثبت `openclaw plugins install` تبعيات الإضافة باستخدام +`npm install --omit=dev --ignore-scripts` (من دون lifecycle scripts، ومن +دون تبعيات تطوير في وقت التشغيل). أبقِ أشجار تبعيات الإضافة "JavaScript/TypeScript +نقية" وتجنب الحزم التي تتطلب بناء `postinstall`. -اختياري: يمكن أن يشير `openclaw.setupEntry` إلى وحدة إعداد خفيفة فقط. -عندما يحتاج OpenClaw إلى أسطح إعداد لإضافة قناة معطلة، أو -عندما تكون إضافة القناة مفعلة لكنها لا تزال غير مهيأة، فإنه يحمّل `setupEntry` -بدل مدخل الإضافة الكامل. ويُبقي ذلك بدء التشغيل والإعداد أخف -عندما يكون مدخل الإضافة الرئيسي لديك يربط أيضًا أدوات أو خطافات أو -شيفرة وقت تشغيل فقط أخرى. +اختياري: يمكن لـ `openclaw.setupEntry` الإشارة إلى وحدة خفيفة مخصصة +للإعداد فقط. وعندما يحتاج OpenClaw إلى أسطح إعداد لإضافة قناة معطّلة، أو +عندما تكون إضافة القناة مفعلة لكنها لا تزال غير مهيأة، فإنه يحمّل +`setupEntry` بدلًا من مدخل الإضافة الكامل. وهذا يجعل بدء التشغيل والإعداد +أخف عندما يكون مدخل الإضافة الرئيسي لديك يربط أيضًا أدوات أو خطافات أو +شيفرة أخرى خاصة بوقت التشغيل فقط. -اختياري: يمكن لـ `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` -إدخال إضافة القناة في المسار نفسه لـ `setupEntry` أثناء مرحلة بدء التشغيل قبل -الاستماع في البوابة، حتى عندما تكون القناة مهيأة بالفعل. +اختياري: يمكن لـ +`openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` +إدخال إضافة قناة في مسار `setupEntry` نفسه أثناء مرحلة بدء التشغيل السابقة +للاستماع في gateway، حتى عندما تكون القناة مهيأة بالفعل. -استخدم هذا فقط عندما يغطي `setupEntry` بالكامل سطح بدء التشغيل الذي يجب أن يوجد -قبل أن تبدأ البوابة في الاستماع. وعمليًا، يعني ذلك أن مدخل الإعداد -يجب أن يسجل كل قدرة تملكها القناة ويعتمد عليها بدء التشغيل، مثل: +استخدم هذا فقط عندما يغطي `setupEntry` بالكامل سطح بدء التشغيل الذي يجب أن +يوجد قبل أن يبدأ gateway الاستماع. وعمليًا، يعني ذلك أن مدخل الإعداد يجب أن +يسجل كل إمكانية مملوكة للقناة يعتمد عليها بدء التشغيل، مثل: - تسجيل القناة نفسها -- أي مسارات HTTP يجب أن تكون متاحة قبل أن تبدأ البوابة في الاستماع -- أي أساليب أو أدوات أو خدمات Gateway يجب أن توجد خلال النافذة نفسها +- أي مسارات HTTP يجب أن تكون متاحة قبل أن يبدأ gateway الاستماع +- أي أساليب gateway أو أدوات أو خدمات يجب أن توجد خلال النافذة نفسها -إذا كان المدخل الكامل لا يزال يملك أي قدرة مطلوبة عند بدء التشغيل، فلا -تفعّل هذا العلم. أبقِ الإضافة على السلوك الافتراضي ودع OpenClaw يحمّل +إذا كان مدخلك الكامل لا يزال يملك أي إمكانية مطلوبة عند بدء التشغيل، فلا +تفعّل هذا العلم. وأبقِ الإضافة على السلوك الافتراضي ودع OpenClaw يحمّل المدخل الكامل أثناء بدء التشغيل. -يمكن للقنوات المجمعة أيضًا نشر مساعدات لسطح العقد خاصة بالإعداد فقط يمكن للنواة -استشارتها قبل تحميل وقت تشغيل القناة الكامل. وسطح ترقية الإعداد الحالي هو: +يمكن للقنوات المضمّنة أيضًا نشر مساعدات لسطح العقد مخصصة للإعداد فقط بحيث +تستطيع النواة الرجوع إليها قبل تحميل وقت تشغيل القناة الكامل. وسطح ترقية +الإعداد الحالي هو: - `singleAccountKeysToMove` - `namedAccountPromotionKeys` - `resolveSingleAccountPromotionTarget(...)` -تستخدم النواة هذا السطح عندما تحتاج إلى ترقية إعداد قناة قديم أحادي الحساب -إلى `channels..accounts.*` من دون تحميل مدخل الإضافة الكامل. -وتمثل Matrix المثال المجمع الحالي: فهي تنقل فقط مفاتيح -المصادقة/التمهيد إلى حساب مسمى مُرقّى عندما تكون الحسابات المسمّاة موجودة -بالفعل، ويمكنها الحفاظ على مفتاح حساب افتراضي غير قياسي مضبوط بدل إنشاء +تستخدم النواة هذا السطح عندما تحتاج إلى ترقية إعداد قناة قديم ذي حساب +واحد إلى `channels..accounts.*` من دون تحميل مدخل الإضافة الكامل. +وتمثل Matrix المثال المضمّن الحالي: فهي تنقل مفاتيح المصادقة/التهيئة +الأولية فقط إلى حساب مسمّى مُرقّى عند وجود حسابات مسمّاة بالفعل، ويمكنها +الحفاظ على مفتاح حساب افتراضي غير قانوني مهيأ بدلًا من إنشاء `accounts.default` دائمًا. -تحافظ محولات رقع الإعداد هذه على كسل اكتشاف سطح العقد المجمعة. فيبقى -وقت الاستيراد خفيفًا؛ ولا يُحمَّل سطح الترقية إلا عند أول استخدام بدل -إعادة إدخال بدء تشغيل القناة المجمعة عند استيراد الوحدة. +وتحافظ مكيّفات ترقيع الإعداد هذه على كسَل اكتشاف سطح العقد المضمّن. +فيبقى وقت الاستيراد خفيفًا؛ ويُحمَّل سطح الترقية عند أول استخدام فقط بدلًا +من إعادة الدخول إلى بدء تشغيل القناة المضمّنة عند استيراد الوحدة. -وعندما تتضمن أسطح بدء التشغيل هذه أساليب Gateway RPC، فأبقها تحت -بادئة خاصة بالإضافة. تظل مساحات أسماء إدارة النواة (`config.*`, +وعندما تتضمن أسطح بدء التشغيل هذه أساليب Gateway RPC، فأبقها على بادئة +خاصة بالإضافة. وتظل مساحات أسماء إدارة النواة (`config.*`، `exec.approvals.*`, `wizard.*`, `update.*`) محجوزة وتُحل دائمًا إلى -`operator.admin`, حتى لو طلبت الإضافة نطاقًا أضيق. +`operator.admin`، حتى إذا طلبت إضافة نطاقًا أضيق. مثال: @@ -1435,10 +1504,11 @@ api.registerHttpRoute({ } ``` -### بيانات كتالوج القنوات الوصفية +### البيانات الوصفية لكتالوج القنوات -يمكن لإضافات القنوات الإعلان عن بيانات وصفية للإعداد/الاكتشاف عبر `openclaw.channel` و -تلميحات التثبيت عبر `openclaw.install`. وهذا يبقي بيانات الكتالوج الأساسية خالية من البيانات. +يمكن لإضافات القنوات الإعلان عن بيانات وصفية للإعداد/الاكتشاف عبر +`openclaw.channel`، وتلميحات التثبيت عبر `openclaw.install`. وهذا يُبقي +بيانات الكتالوج الأساسية خالية من البيانات. مثال: @@ -1468,40 +1538,51 @@ api.registerHttpRoute({ حقول `openclaw.channel` المفيدة إلى جانب المثال الأدنى: -- `detailLabel`: تسمية ثانوية لأسطح الكتالوج/الحالة الأكثر ثراءً +- `detailLabel`: تسمية ثانوية لأسطح الكتالوج/الحالة الأكثر غنى - `docsLabel`: تجاوز نص الرابط الخاص بالوثائق -- `preferOver`: معرّفات إضافات/قنوات أقل أولوية يجب أن تتقدم هذه المدخلة في الكتالوج عليها -- `selectionDocsPrefix`, و`selectionDocsOmitLabel`, و`selectionExtras`: عناصر تحكم في نسخة سطح الاختيار -- `markdownCapable`: يحدد القناة على أنها قادرة على Markdown لقرارات التنسيق الصادر -- `exposure.configured`: إخفاء القناة من أسطح قائمة القنوات المهيأة عند تعيينها إلى `false` -- `exposure.setup`: إخفاء القناة من منتقيات الإعداد/التهيئة التفاعلية عند تعيينها إلى `false` -- `exposure.docs`: تحديد القناة على أنها داخلية/خاصة لأسطح التنقل في الوثائق -- `showConfigured` / `showInSetup`: أسماء مستعارة قديمة لا تزال مقبولة للتوافق؛ ويفضل `exposure` -- `quickstartAllowFrom`: إدخال القناة في تدفق `allowFrom` القياسي للبدء السريع -- `forceAccountBinding`: فرض ربط حساب صريح حتى عند وجود حساب واحد فقط -- `preferSessionLookupForAnnounceTarget`: تفضيل بحث الجلسة عند حل أهداف الإعلانات +- `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"`. ## إضافات محرك السياق -تملك إضافات محرك السياق تنسيق سياق الجلسة من أجل الإدخال، والتجميع، +تملك إضافات محرك السياق تنسيق سياق الجلسة لعمليات الإدخال، والتجميع، والضغط. سجّلها من إضافتك باستخدام -`api.registerContextEngine(id, factory)`, ثم اختر المحرك النشط باستخدام +`api.registerContextEngine(id, factory)`، ثم اختر المحرك النشط باستخدام `plugins.slots.contextEngine`. استخدم هذا عندما تحتاج إضافتك إلى استبدال مسار السياق الافتراضي أو توسيعه -بدل مجرد إضافة بحث في الذاكرة أو خطافات. +بدلًا من مجرد إضافة بحث في الذاكرة أو خطافات. ```ts import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core"; @@ -1529,8 +1610,8 @@ export default function (api) { } ``` -إذا كان محركك **لا** يملك خوارزمية الضغط، فاحتفظ بتنفيذ `compact()` -وفوّضها صراحة: +إذا كان محركك **لا** يملك خوارزمية الضغط، فأبقِ `compact()` منفذة وقم +بتفويضها صراحةً: ```ts import { @@ -1565,62 +1646,62 @@ export default function (api) { } ``` -## إضافة قدرة جديدة +## إضافة إمكانية جديدة -عندما تحتاج إضافة إلى سلوك لا يناسب واجهة البرمجة الحالية، فلا تتجاوز -نظام الإضافات عبر وصول خاص. أضف القدرة المفقودة. +عندما تحتاج إضافة ما إلى سلوك لا يلائم واجهة API الحالية، فلا تتجاوز نظام +الإضافات عبر وصول خاص داخلي. أضف الإمكانية الناقصة. التسلسل الموصى به: -1. تعريف العقد الأساسي - قرر السلوك المشترك الذي يجب أن تملكه النواة: السياسة، وآلية التراجع، ودمج الإعدادات، - ودورة الحياة، والدلالات المواجهة للقنوات، وشكل مساعد وقت التشغيل. -2. إضافة أسطح تسجيل/وقت تشغيل مكتوبة الأنواع - وسّع `OpenClawPluginApi` و/أو `api.runtime` بأصغر - سطح قدرة مكتوب الأنواع ومفيد. -3. توصيل مستهلكي النواة + القنوات/الميزات - يجب أن تستهلك القنوات وإضافات الميزات القدرة الجديدة عبر النواة، - لا عبر استيراد تنفيذ مورد مباشرة. -4. تسجيل تنفيذات المورد - ثم تسجل إضافات المورد واجهاتها الخلفية مقابل القدرة. -5. إضافة تغطية للعقد - أضف اختبارات حتى تبقى الملكية وشكل التسجيل واضحين مع الوقت. +1. عرّف عقد النواة + حدّد السلوك المشترك الذي ينبغي أن تملكه النواة: السياسات، وآليات + التراجع، ودمج الإعدادات، ودورة الحياة، والدلالات الموجهة للقنوات، + وشكل مساعد وقت التشغيل. +2. أضف أسطح تسجيل/وقت تشغيل مكتوبة Typed للإضافات + وسّع `OpenClawPluginApi` و/أو `api.runtime` بأصغر سطح إمكانيات مكتوب + Typed مفيد. +3. اربط مستهلكي النواة + القنوات/الميزات + ينبغي أن تستهلك إضافات القنوات والميزات الإمكانية الجديدة عبر النواة، + لا عبر استيراد تنفيذ مورّد مباشرةً. +4. سجّل تنفيذات المورّدين + بعدها تسجّل إضافات المورّدين واجهاتها الخلفية ضمن الإمكانية. +5. أضف تغطية للعقد + أضف اختبارات بحيث تبقى الملكية وشكل التسجيل صريحين مع الزمن. -هكذا يحافظ OpenClaw على وضوح رؤيته من دون أن يصبح مرمّزًا على -منظور مزود واحد. راجع [دفتر وصفات القدرات](/ar/plugins/architecture) -للحصول على قائمة ملفات عملية ومثال منجز. +هكذا يبقى OpenClaw ذا توجه واضح من دون أن يصبح مضمّنًا لرؤية مورّد واحد +للعالم. راجع [دليل الإمكانات العملي](/ar/plugins/architecture) للحصول على +قائمة ملفات عملية ومثال مفصّل. -### قائمة تحقق القدرة +### قائمة تحقق الإمكانية -عند إضافة قدرة جديدة، يجب عادةً أن يطال التنفيذ هذه -الأسطح معًا: +عند إضافة إمكانية جديدة، ينبغي عادةً أن يلمس التنفيذ هذه الأسطح معًا: -- أنواع العقود الأساسية في `src//types.ts` -- المشغّل/مساعد وقت التشغيل الأساسي في `src//runtime.ts` -- سطح تسجيل واجهة برمجة الإضافة في `src/plugins/types.ts` -- توصيل سجل الإضافات في `src/plugins/registry.ts` -- كشف وقت تشغيل الإضافة في `src/plugins/runtime/*` عندما تحتاج - إضافات الميزات/القنوات إلى استهلاكه +- أنواع عقد النواة في `src//types.ts` +- مساعد العارض/وقت التشغيل في النواة في `src//runtime.ts` +- سطح تسجيل واجهة API للإضافة في `src/plugins/types.ts` +- ربط سجل الإضافات في `src/plugins/registry.ts` +- كشف وقت تشغيل الإضافة في `src/plugins/runtime/*` عندما تحتاج إضافات + الميزات/القنوات إلى استهلاكه - مساعدات الالتقاط/الاختبار في `src/test-utils/plugin-registration.ts` - تأكيدات الملكية/العقد في `src/plugins/contracts/registry.ts` -- وثائق المشغل/الإضافات في `docs/` +- وثائق المشغّلين/الإضافات في `docs/` -إذا غاب أحد هذه الأسطح، فهذه غالبًا علامة على أن القدرة لم تُدمج -بالكامل بعد. +إذا كان أحد هذه الأسطح مفقودًا، فعادةً ما تكون هذه إشارة إلى أن الإمكانية +لم تُدمج بالكامل بعد. -### قالب القدرة +### قالب الإمكانية -الحد الأدنى من النمط: +النمط الأدنى: ```ts -// العقد الأساسي +// core contract export type VideoGenerationProviderPlugin = { id: string; label: string; generateVideo: (req: VideoGenerationRequest) => Promise; }; -// واجهة برمجة الإضافة +// plugin API api.registerVideoGenerationProvider({ id: "openai", label: "OpenAI", @@ -1629,7 +1710,7 @@ api.registerVideoGenerationProvider({ }, }); -// مساعد وقت تشغيل مشترك لإضافات الميزات/القنوات +// shared runtime helper for feature/channel plugins const clip = await api.runtime.videoGeneration.generate({ prompt: "Show the robot walking through the lab.", cfg, @@ -1644,7 +1725,7 @@ expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]); وهذا يبقي القاعدة بسيطة: -- تملك النواة عقد القدرة + التنسيق -- تملك إضافات المورد تنفيذات المورد +- تملك النواة عقد الإمكانية + التنسيق +- تملك إضافات المورّدين تنفيذات المورّد - تستهلك إضافات الميزات/القنوات مساعدات وقت التشغيل -- تُبقي اختبارات العقود الملكية واضحة +- تُبقي اختبارات العقود الملكية صريحة diff --git a/docs/ar/plugins/manifest.md b/docs/ar/plugins/manifest.md index 7703f172d..9dbe88d2b 100644 --- a/docs/ar/plugins/manifest.md +++ b/docs/ar/plugins/manifest.md @@ -1,75 +1,80 @@ --- read_when: - - أنت تقوم ببناء plugin لـ OpenClaw. - - تحتاج إلى إصدار مخطط إعدادات plugin أو تصحيح أخطاء التحقق من صحة plugin. -summary: بيان plugin + متطلبات JSON schema (التحقق الصارم من صحة الإعدادات) -title: بيان plugin + - أنت تقوم ببناء مكون إضافي لـ OpenClaw + - تحتاج إلى توفير مخطط لتكوين المكون الإضافي أو تصحيح أخطاء التحقق من صحة المكون الإضافي +summary: متطلبات بيان المكون الإضافي + مخطط JSON (تحقق صارم من صحة التكوين) +title: بيان المكون الإضافي x-i18n: - generated_at: "2026-04-11T02:46:07Z" + generated_at: "2026-04-11T15:16:00Z" model: gpt-5.4 provider: openai - source_hash: 6b254c121d1eb5ea19adbd4148243cf47339c960442ab1ca0e0bfd52e0154c88 + source_hash: 42d454b560a8f6bf714c5d782f34216be1216d83d0a319d08d7349332c91a9e4 source_path: plugins/manifest.md workflow: 15 --- -# بيان plugin (`openclaw.plugin.json`) +# بيان المكون الإضافي (`openclaw.plugin.json`) -هذه الصفحة مخصصة فقط لـ **بيان OpenClaw الأصلي لـ plugin**. +هذه الصفحة مخصصة لـ **بيان المكون الإضافي الأصلي في OpenClaw** فقط. -للتنسيقات المتوافقة للحزم، راجع [حزم plugin](/ar/plugins/bundles). +للاطلاع على تخطيطات الحزم المتوافقة، راجع [حزم المكونات الإضافية](/ar/plugins/bundles). تستخدم تنسيقات الحزم المتوافقة ملفات بيان مختلفة: - حزمة Codex: `.codex-plugin/plugin.json` -- حزمة Claude: `.claude-plugin/plugin.json` أو تخطيط مكونات Claude - الافتراضي من دون بيان +- حزمة Claude: `.claude-plugin/plugin.json` أو تخطيط مكونات Claude الافتراضي + بدون بيان - حزمة Cursor: `.cursor-plugin/plugin.json` يكتشف OpenClaw تلك التخطيطات المتوافقة للحزم تلقائيًا أيضًا، لكنها لا تُتحقق -مقارنتها بمخطط `openclaw.plugin.json` الموضح هنا. +مقابل مخطط `openclaw.plugin.json` الموضح هنا. بالنسبة إلى الحزم المتوافقة، يقرأ OpenClaw حاليًا بيانات الحزمة الوصفية بالإضافة إلى -جذور Skills المعلنة، وجذور أوامر Claude، وقيم `settings.json` الافتراضية في حزمة Claude، -وقيم LSP الافتراضية في حزمة Claude، وحزم hooks المدعومة عندما يطابق التخطيط +جذور Skills المعلنة، وجذور أوامر Claude، والقيم الافتراضية لملف `settings.json` في حزمة Claude، +والقيم الافتراضية لـ Claude bundle LSP، وحزم hooks المدعومة عندما يطابق التخطيط توقعات وقت تشغيل OpenClaw. -يجب على كل plugin أصلي في OpenClaw **أن** يوفّر ملف `openclaw.plugin.json` في -**جذر plugin**. يستخدم OpenClaw هذا البيان للتحقق من صحة الإعدادات -**من دون تنفيذ كود plugin**. وتُعامل البيانات المفقودة أو غير الصالحة على أنها -أخطاء plugin وتمنع التحقق من صحة الإعدادات. +يجب على كل مكون إضافي أصلي في OpenClaw **أن يتضمن** ملف `openclaw.plugin.json` في +**جذر المكون الإضافي**. يستخدم OpenClaw هذا البيان للتحقق من صحة التكوين +**من دون تنفيذ كود المكون الإضافي**. تُعامل البيانات المفقودة أو غير الصالحة على أنها +أخطاء في المكون الإضافي وتمنع التحقق من صحة التكوين. -راجع الدليل الكامل لنظام plugin: [Plugins](/ar/tools/plugin). -وبالنسبة إلى نموذج الإمكانات الأصلي والإرشادات الحالية للتوافق الخارجي: -[نموذج الإمكانات](/ar/plugins/architecture#public-capability-model). +راجع الدليل الكامل لنظام المكونات الإضافية: [المكونات الإضافية](/ar/tools/plugin). +وللاطلاع على نموذج القدرات الأصلي وإرشادات التوافق الخارجي الحالية: +[نموذج القدرات](/ar/plugins/architecture#public-capability-model). ## ما الذي يفعله هذا الملف -`openclaw.plugin.json` هو البيانات الوصفية التي يقرؤها OpenClaw قبل أن يحمّل -كود plugin الخاص بك. +`openclaw.plugin.json` هو البيانات الوصفية التي يقرأها OpenClaw قبل أن يحمّل +كود المكون الإضافي الخاص بك. استخدمه من أجل: -- هوية plugin -- التحقق من صحة الإعدادات -- بيانات المصادقة والإعداد الأولي التي يجب أن تكون متاحة من دون تشغيل وقت تشغيل plugin -- بيانات الأسماء المستعارة والتمكين التلقائي التي يجب أن تُحل قبل تحميل وقت تشغيل plugin -- بيانات ملكية عائلة النماذج المختصرة التي ينبغي أن تفعّل - plugin تلقائيًا قبل تحميل وقت التشغيل -- لقطات ثابتة لملكية الإمكانات تُستخدم في توافق الحزم والتغطية التعاقدية -- بيانات إعدادات خاصة بالقنوات ينبغي دمجها في أسطح الفهرسة والتحقق +- هوية المكون الإضافي +- التحقق من صحة التكوين +- بيانات التعريف الخاصة بالمصادقة والإعداد الأولي التي يجب أن تكون متاحة من دون تشغيل + وقت تشغيل المكون الإضافي +- تلميحات تفعيل منخفضة التكلفة يمكن لأسطح control-plane فحصها قبل تحميل وقت التشغيل +- واصفات إعداد منخفضة التكلفة يمكن لأسطح الإعداد/التهيئة الأولية فحصها قبل + تحميل وقت التشغيل +- بيانات تعريف الأسماء المستعارة والتمكين التلقائي التي يجب حلها قبل تحميل وقت تشغيل + المكون الإضافي +- بيانات تعريف مختصرة لملكية عائلة النماذج ينبغي أن تفعّل + المكون الإضافي تلقائيًا قبل تحميل وقت التشغيل +- لقطات ثابتة لملكية القدرات تُستخدم في ربط التوافق المضمّن وتغطية العقود +- بيانات تعريف تكوين خاصة بالقنوات ينبغي دمجها في أسطح الفهرسة والتحقق من دون تحميل وقت التشغيل -- تلميحات UI للإعدادات +- تلميحات واجهة المستخدم للتكوين لا تستخدمه من أجل: - تسجيل سلوك وقت التشغيل -- تعريف نقاط إدخال الكود -- بيانات تثبيت npm +- تعريف نقاط دخول الكود +- بيانات تعريف تثبيت npm -هذه تنتمي إلى كود plugin الخاص بك و`package.json`. +هذه تنتمي إلى كود المكون الإضافي الخاص بك و`package.json`. -## مثال أدنى +## مثال بسيط ```json { @@ -82,13 +87,13 @@ x-i18n: } ``` -## مثال موسع +## مثال غني ```json { "id": "openrouter", "name": "OpenRouter", - "description": "plugin مزود OpenRouter", + "description": "OpenRouter provider plugin", "version": "1.0.0", "providers": ["openrouter"], "modelSupport": { @@ -109,19 +114,19 @@ x-i18n: "provider": "openrouter", "method": "api-key", "choiceId": "openrouter-api-key", - "choiceLabel": "مفتاح API لـ OpenRouter", + "choiceLabel": "OpenRouter API key", "groupId": "openrouter", "groupLabel": "OpenRouter", "optionKey": "openrouterApiKey", "cliFlag": "--openrouter-api-key", "cliOption": "--openrouter-api-key ", - "cliDescription": "مفتاح API لـ OpenRouter", + "cliDescription": "OpenRouter API key", "onboardingScopes": ["text-inference"] } ], "uiHints": { "apiKey": { - "label": "مفتاح API", + "label": "API key", "placeholder": "sk-or-v1-...", "sensitive": true } @@ -140,60 +145,62 @@ x-i18n: ## مرجع الحقول ذات المستوى الأعلى -| الحقل | مطلوب | النوع | معناه | -| ----------------------------------- | ------ | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `id` | نعم | `string` | معرّف plugin الأساسي. وهذا هو المعرّف المستخدم في `plugins.entries.`. | -| `configSchema` | نعم | `object` | JSON Schema مضمن لإعدادات هذا plugin. | -| `enabledByDefault` | لا | `true` | يحدد أن plugin المجمّع مفعّل افتراضيًا. احذف هذا الحقل، أو اضبطه على أي قيمة غير `true`، للإبقاء على plugin معطلًا افتراضيًا. | -| `legacyPluginIds` | لا | `string[]` | معرّفات قديمة تُطبّع إلى معرّف plugin الأساسي هذا. | -| `autoEnableWhenConfiguredProviders` | لا | `string[]` | معرّفات المزودات التي يجب أن تفعّل هذا plugin تلقائيًا عندما تشير إليها المصادقة أو الإعدادات أو مراجع النماذج. | -| `kind` | لا | `"memory"` \| `"context-engine"` | يعلن نوع plugin حصريًا يُستخدم بواسطة `plugins.slots.*`. | -| `channels` | لا | `string[]` | معرّفات القنوات التي يملكها هذا plugin. تُستخدم للاكتشاف والتحقق من صحة الإعدادات. | -| `providers` | لا | `string[]` | معرّفات المزودات التي يملكها هذا plugin. | -| `modelSupport` | لا | `object` | بيانات وصفية مختصرة لعائلات النماذج يملكها البيان وتُستخدم لتحميل plugin تلقائيًا قبل وقت التشغيل. | -| `cliBackends` | لا | `string[]` | معرّفات الواجهات الخلفية للاستدلال في CLI التي يملكها هذا plugin. وتُستخدم للتفعيل التلقائي عند بدء التشغيل من مراجع الإعدادات الصريحة. | -| `commandAliases` | لا | `object[]` | أسماء الأوامر التي يملكها هذا plugin والتي ينبغي أن تنتج إعدادات خاصة بالـ plugin وتشخيصات CLI قبل تحميل وقت التشغيل. | -| `providerAuthEnvVars` | لا | `Record` | بيانات وصفية بسيطة لمتغيرات بيئة مصادقة المزود يمكن لـ OpenClaw فحصها من دون تحميل كود plugin. | -| `providerAuthAliases` | لا | `Record` | معرّفات مزودات ينبغي أن تعيد استخدام معرّف مزود آخر للبحث عن المصادقة، مثل مزود coding يشارك مفتاح API الأساسي وملفات تعريف المصادقة الخاصة بالمزود الأساسي. | -| `channelEnvVars` | لا | `Record` | بيانات وصفية بسيطة لمتغيرات بيئة القنوات يمكن لـ OpenClaw فحصها من دون تحميل كود plugin. استخدم هذا للإعداد المعتمد على البيئة للقنوات أو أسطح المصادقة التي ينبغي أن تراها أدوات البدء/الإعداد العامة. | -| `providerAuthChoices` | لا | `object[]` | بيانات وصفية بسيطة لخيارات المصادقة لمحددات الإعداد الأولي، وحل المزود المفضل، وربط أعلام CLI البسيطة. | -| `contracts` | لا | `object` | لقطة ثابتة لإمكانات الحزم للتعرف على الكلام، والنسخ الفوري، والصوت الفوري، وفهم الوسائط، وتوليد الصور، وتوليد الموسيقى، وتوليد الفيديو، وweb-fetch، وweb search، وملكية الأدوات. | -| `channelConfigs` | لا | `Record` | بيانات وصفية لإعدادات القنوات يملكها البيان وتُدمج في أسطح الاكتشاف والتحقق قبل تحميل وقت التشغيل. | -| `skills` | لا | `string[]` | أدلة Skills المطلوب تحميلها، نسبةً إلى جذر plugin. | -| `name` | لا | `string` | اسم plugin قابل للقراءة البشرية. | -| `description` | لا | `string` | ملخص قصير يظهر في أسطح plugin. | -| `version` | لا | `string` | إصدار plugin معلوماتي. | -| `uiHints` | لا | `Record` | تسميات UI، وعناصر نائبة، وتلميحات الحساسية لحقول الإعدادات. | +| الحقل | مطلوب | النوع | ما الذي يعنيه | +| ----------------------------------- | ------ | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | نعم | `string` | المعرّف الأساسي للمكون الإضافي. هذا هو المعرّف المستخدم في `plugins.entries.`. | +| `configSchema` | نعم | `object` | مخطط JSON مضمن لتكوين هذا المكون الإضافي. | +| `enabledByDefault` | لا | `true` | يحدد مكونًا إضافيًا مضمّنًا على أنه مفعّل افتراضيًا. احذف هذا الحقل، أو عيّن أي قيمة غير `true`، لترك المكون الإضافي معطلًا افتراضيًا. | +| `legacyPluginIds` | لا | `string[]` | معرّفات قديمة تُطبَّع إلى هذا المعرّف الأساسي للمكون الإضافي. | +| `autoEnableWhenConfiguredProviders` | لا | `string[]` | معرّفات الموفرين التي يجب أن تفعّل هذا المكون الإضافي تلقائيًا عندما تشير المصادقة أو التكوين أو مراجع النماذج إليها. | +| `kind` | لا | `"memory"` \| `"context-engine"` | يعلن نوع مكون إضافي حصريًا يُستخدم بواسطة `plugins.slots.*`. | +| `channels` | لا | `string[]` | معرّفات القنوات المملوكة لهذا المكون الإضافي. تُستخدم للاكتشاف والتحقق من صحة التكوين. | +| `providers` | لا | `string[]` | معرّفات الموفرين المملوكة لهذا المكون الإضافي. | +| `modelSupport` | لا | `object` | بيانات تعريف مختصرة مملوكة للبيان لعائلة النماذج، وتُستخدم لتحميل المكون الإضافي تلقائيًا قبل وقت التشغيل. | +| `cliBackends` | لا | `string[]` | معرّفات الواجهات الخلفية للاستدلال في CLI المملوكة لهذا المكون الإضافي. تُستخدم للتفعيل التلقائي عند بدء التشغيل انطلاقًا من مراجع التكوين الصريحة. | +| `commandAliases` | لا | `object[]` | أسماء الأوامر المملوكة لهذا المكون الإضافي والتي ينبغي أن تُنتج تشخيصات واعية بالمكون الإضافي للتكوين وCLI قبل تحميل وقت التشغيل. | +| `providerAuthEnvVars` | لا | `Record` | بيانات تعريف منخفضة التكلفة لمتغيرات البيئة الخاصة بمصادقة الموفر، ويمكن لـ OpenClaw فحصها من دون تحميل كود المكون الإضافي. | +| `providerAuthAliases` | لا | `Record` | معرّفات موفرين يجب أن تعيد استخدام معرّف موفر آخر للبحث عن المصادقة، مثل موفر برمجة يشارك مفتاح API الأساسي وملفات تعريف المصادقة الخاصة بالموفر الأساسي. | +| `channelEnvVars` | لا | `Record` | بيانات تعريف منخفضة التكلفة لمتغيرات بيئة القنوات، ويمكن لـ OpenClaw فحصها من دون تحميل كود المكون الإضافي. استخدم هذا لأسطح إعداد القنوات أو المصادقة المعتمدة على متغيرات البيئة والتي ينبغي أن تراها أدوات البدء/التكوين العامة. | +| `providerAuthChoices` | لا | `object[]` | بيانات تعريف منخفضة التكلفة لخيارات المصادقة لمحددات الإعداد الأولي، وحل الموفر المفضل، وربط أعلام CLI البسيط. | +| `activation` | لا | `object` | تلميحات تفعيل منخفضة التكلفة للتحميل المُحفَّز بواسطة الموفر أو الأمر أو القناة أو المسار أو القدرة. بيانات تعريف فقط؛ لا يزال وقت تشغيل المكون الإضافي يملك السلوك الفعلي. | +| `setup` | لا | `object` | واصفات إعداد/تهيئة أولية منخفضة التكلفة يمكن لأسطح الاكتشاف والإعداد فحصها من دون تحميل وقت تشغيل المكون الإضافي. | +| `contracts` | لا | `object` | لقطة ثابتة للقدرات المضمّنة من أجل speech، وrealtime transcription، وrealtime voice، وmedia-understanding، وimage-generation، وmusic-generation، وvideo-generation، وweb-fetch، وweb search، وملكية الأدوات. | +| `channelConfigs` | لا | `Record` | بيانات تعريف تكوين القنوات المملوكة للبيان والمُدمجة في أسطح الاكتشاف والتحقق من الصحة قبل تحميل وقت التشغيل. | +| `skills` | لا | `string[]` | أدلة Skills التي سيتم تحميلها، نسبةً إلى جذر المكون الإضافي. | +| `name` | لا | `string` | اسم مقروء بشريًا للمكون الإضافي. | +| `description` | لا | `string` | ملخص قصير يظهر في أسطح المكونات الإضافية. | +| `version` | لا | `string` | إصدار معلوماتي للمكون الإضافي. | +| `uiHints` | لا | `Record` | تسميات واجهة المستخدم والعناصر النائبة وتلميحات الحساسية لحقول التكوين. | ## مرجع `providerAuthChoices` يصف كل إدخال في `providerAuthChoices` خيارًا واحدًا للإعداد الأولي أو المصادقة. -يقرأ OpenClaw هذا قبل تحميل وقت تشغيل المزود. +يقرأ OpenClaw هذا قبل تحميل وقت تشغيل الموفر. -| الحقل | مطلوب | النوع | معناه | -| --------------------- | ------ | ----------------------------------------------- | ---------------------------------------------------------------------------------------------- | -| `provider` | نعم | `string` | معرّف المزود الذي ينتمي إليه هذا الخيار. | -| `method` | نعم | `string` | معرّف طريقة المصادقة المطلوب التوجيه إليها. | -| `choiceId` | نعم | `string` | معرّف ثابت لخيار المصادقة تستخدمه عمليات الإعداد الأولي وCLI. | -| `choiceLabel` | لا | `string` | تسمية موجهة للمستخدم. وإذا حُذفت، يعود OpenClaw إلى `choiceId`. | -| `choiceHint` | لا | `string` | نص مساعد قصير للمحدد. | -| `assistantPriority` | لا | `number` | القيم الأقل تُرتَّب أولًا في المحددات التفاعلية التي يقودها المساعد. | -| `assistantVisibility` | لا | `"visible"` \| `"manual-only"` | إخفاء الخيار من محددات المساعد مع الاستمرار في السماح باختياره يدويًا عبر CLI. | -| `deprecatedChoiceIds` | لا | `string[]` | معرّفات خيارات قديمة ينبغي إعادة توجيه المستخدمين منها إلى هذا الخيار البديل. | -| `groupId` | لا | `string` | معرّف مجموعة اختياري لتجميع الخيارات المرتبطة. | -| `groupLabel` | لا | `string` | تسمية موجهة للمستخدم لتلك المجموعة. | -| `groupHint` | لا | `string` | نص مساعد قصير للمجموعة. | -| `optionKey` | لا | `string` | مفتاح خيار داخلي لتدفقات المصادقة البسيطة ذات العلم الواحد. | -| `cliFlag` | لا | `string` | اسم علم CLI، مثل `--openrouter-api-key`. | -| `cliOption` | لا | `string` | الشكل الكامل لخيار CLI، مثل `--openrouter-api-key `. | -| `cliDescription` | لا | `string` | الوصف المستخدم في تعليمات CLI. | -| `onboardingScopes` | لا | `Array<"text-inference" \| "image-generation">` | أسطح الإعداد الأولي التي ينبغي أن يظهر فيها هذا الخيار. وإذا حُذفت، تكون القيمة الافتراضية `["text-inference"]`. | +| الحقل | مطلوب | النوع | ما الذي يعنيه | +| --------------------- | ------ | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------ | +| `provider` | نعم | `string` | معرّف الموفر الذي ينتمي إليه هذا الخيار. | +| `method` | نعم | `string` | معرّف أسلوب المصادقة الذي سيتم التوجيه إليه. | +| `choiceId` | نعم | `string` | معرّف ثابت لخيار المصادقة يُستخدم بواسطة تدفقات الإعداد الأولي وCLI. | +| `choiceLabel` | لا | `string` | تسمية موجهة للمستخدم. إذا حُذفت، يعود OpenClaw إلى `choiceId`. | +| `choiceHint` | لا | `string` | نص مساعد قصير للمحدد. | +| `assistantPriority` | لا | `number` | تُرتَّب القيم الأقل أولًا في المحددات التفاعلية التي يقودها المساعد. | +| `assistantVisibility` | لا | `"visible"` \| `"manual-only"` | يُخفي الخيار من محددات المساعد مع الاستمرار في السماح بالاختيار اليدوي عبر CLI. | +| `deprecatedChoiceIds` | لا | `string[]` | معرّفات خيارات قديمة ينبغي أن تعيد توجيه المستخدمين إلى هذا الخيار البديل. | +| `groupId` | لا | `string` | معرّف مجموعة اختياري لتجميع الخيارات المرتبطة. | +| `groupLabel` | لا | `string` | تسمية موجهة للمستخدم لتلك المجموعة. | +| `groupHint` | لا | `string` | نص مساعد قصير للمجموعة. | +| `optionKey` | لا | `string` | مفتاح خيار داخلي لتدفقات المصادقة البسيطة ذات العلم الواحد. | +| `cliFlag` | لا | `string` | اسم علم CLI، مثل `--openrouter-api-key`. | +| `cliOption` | لا | `string` | صيغة خيار CLI الكاملة، مثل `--openrouter-api-key `. | +| `cliDescription` | لا | `string` | الوصف المستخدم في تعليمات CLI. | +| `onboardingScopes` | لا | `Array<"text-inference" \| "image-generation">` | أسطح الإعداد الأولي التي ينبغي أن يظهر فيها هذا الخيار. إذا حُذفت، فالقيمة الافتراضية هي `["text-inference"]`. | ## مرجع `commandAliases` -استخدم `commandAliases` عندما يملك plugin اسم أمر وقت تشغيل قد -يضعه المستخدمون بالخطأ في `plugins.allow` أو يحاولون تشغيله كأمر CLI رئيسي. يستخدم OpenClaw -هذه البيانات الوصفية للتشخيصات من دون استيراد كود وقت تشغيل plugin. +استخدم `commandAliases` عندما يملك المكون الإضافي اسم أمر وقت تشغيل قد يضعه المستخدمون +عن طريق الخطأ في `plugins.allow` أو يحاولون تشغيله كأمر CLI جذري. يستخدم OpenClaw +هذه البيانات الوصفية للتشخيصات من دون استيراد كود وقت تشغيل المكون الإضافي. ```json { @@ -207,22 +214,93 @@ x-i18n: } ``` -| الحقل | مطلوب | النوع | معناه | -| ------------ | ------ | ----------------- | ---------------------------------------------------------------------- | -| `name` | نعم | `string` | اسم الأمر الذي ينتمي إلى هذا plugin. | -| `kind` | لا | `"runtime-slash"` | يحدد الاسم المستعار على أنه أمر slash في الدردشة وليس أمر CLI رئيسيًا. | -| `cliCommand` | لا | `string` | أمر CLI رئيسي ذي صلة لاقتراحه في عمليات CLI، إن وُجد. | +| الحقل | مطلوب | النوع | ما الذي يعنيه | +| ------------ | ------ | ------------------ | ---------------------------------------------------------------------------- | +| `name` | نعم | `string` | اسم الأمر الذي ينتمي إلى هذا المكون الإضافي. | +| `kind` | لا | `"runtime-slash"` | يحدد الاسم المستعار على أنه أمر slash في الدردشة بدلًا من أمر CLI جذري. | +| `cliCommand` | لا | `string` | أمر CLI جذري ذي صلة يُقترح لعمليات CLI، إذا كان موجودًا. | + +## مرجع `activation` + +استخدم `activation` عندما يمكن للمكون الإضافي أن يعلن بتكلفة منخفضة عن أحداث control-plane +التي ينبغي أن تفعّله لاحقًا. + +هذه الكتلة هي بيانات تعريف فقط. وهي لا تسجل سلوك وقت التشغيل، ولا +تحل محل `register(...)` أو `setupEntry` أو نقاط دخول وقت التشغيل/المكون الإضافي الأخرى. + +```json +{ + "activation": { + "onProviders": ["openai"], + "onCommands": ["models"], + "onChannels": ["web"], + "onRoutes": ["gateway-webhook"], + "onCapabilities": ["provider", "tool"] + } +} +``` + +| الحقل | مطلوب | النوع | ما الذي يعنيه | +| ---------------- | ------ | ----------------------------------------------------- | ------------------------------------------------------------- | +| `onProviders` | لا | `string[]` | معرّفات الموفرين التي ينبغي أن تفعّل هذا المكون الإضافي عند طلبها. | +| `onCommands` | لا | `string[]` | معرّفات الأوامر التي ينبغي أن تفعّل هذا المكون الإضافي. | +| `onChannels` | لا | `string[]` | معرّفات القنوات التي ينبغي أن تفعّل هذا المكون الإضافي. | +| `onRoutes` | لا | `string[]` | أنواع المسارات التي ينبغي أن تفعّل هذا المكون الإضافي. | +| `onCapabilities` | لا | `Array<"provider" \| "channel" \| "tool" \| "hook">` | تلميحات قدرات عامة تُستخدم في تخطيط التفعيل ضمن control-plane. | + +## مرجع `setup` + +استخدم `setup` عندما تحتاج أسطح الإعداد والتهيئة الأولية إلى بيانات تعريف منخفضة التكلفة +مملوكة للمكون الإضافي قبل تحميل وقت التشغيل. + +```json +{ + "setup": { + "providers": [ + { + "id": "openai", + "authMethods": ["api-key"], + "envVars": ["OPENAI_API_KEY"] + } + ], + "cliBackends": ["openai-cli"], + "configMigrations": ["legacy-openai-auth"], + "requiresRuntime": false + } +} +``` + +يبقى `cliBackends` على المستوى الأعلى صالحًا ويستمر في وصف الواجهات الخلفية للاستدلال في CLI. +أما `setup.cliBackends` فهو سطح الواصفات الخاص بالإعداد من أجل +تدفقات control-plane/الإعداد التي ينبغي أن تظل بيانات تعريف فقط. + +### مرجع `setup.providers` + +| الحقل | مطلوب | النوع | ما الذي يعنيه | +| ------------- | ------ | ----------- | ------------------------------------------------------------------------------------ | +| `id` | نعم | `string` | معرّف الموفر الذي يُعرَض أثناء الإعداد أو التهيئة الأولية. | +| `authMethods` | لا | `string[]` | معرّفات أساليب الإعداد/المصادقة التي يدعمها هذا الموفر من دون تحميل وقت التشغيل الكامل. | +| `envVars` | لا | `string[]` | متغيرات البيئة التي يمكن لأسطح الإعداد/الحالة العامة التحقق منها قبل تحميل وقت تشغيل المكون الإضافي. | + +### حقول `setup` + +| الحقل | مطلوب | النوع | ما الذي يعنيه | +| ------------------ | ------ | ----------- | ---------------------------------------------------------------------------- | +| `providers` | لا | `object[]` | واصفات إعداد الموفر المعروضة أثناء الإعداد والتهيئة الأولية. | +| `cliBackends` | لا | `string[]` | معرّفات الواجهات الخلفية المتاحة وقت الإعداد من دون تفعيل وقت التشغيل الكامل. | +| `configMigrations` | لا | `string[]` | معرّفات ترحيل التكوين المملوكة لسطح إعداد هذا المكون الإضافي. | +| `requiresRuntime` | لا | `boolean` | ما إذا كان الإعداد لا يزال يحتاج إلى تنفيذ وقت تشغيل المكون الإضافي بعد البحث عن الواصفات. | ## مرجع `uiHints` -`uiHints` عبارة عن خريطة من أسماء حقول الإعدادات إلى تلميحات عرض صغيرة. +`uiHints` هو خريطة من أسماء حقول التكوين إلى تلميحات عرض صغيرة. ```json { "uiHints": { "apiKey": { - "label": "مفتاح API", - "help": "يُستخدم لطلبات OpenRouter", + "label": "API key", + "help": "Used for OpenRouter requests", "placeholder": "sk-or-v1-...", "sensitive": true } @@ -232,19 +310,19 @@ x-i18n: يمكن أن يتضمن كل تلميح حقل ما يلي: -| الحقل | النوع | معناه | -| ------------- | ---------- | -------------------------------------- | -| `label` | `string` | تسمية الحقل الموجهة للمستخدم. | -| `help` | `string` | نص مساعد قصير. | -| `tags` | `string[]` | وسوم UI اختيارية. | -| `advanced` | `boolean` | يحدد الحقل على أنه متقدم. | -| `sensitive` | `boolean` | يحدد الحقل على أنه سري أو حساس. | -| `placeholder` | `string` | نص العنصر النائب لمدخلات النماذج. | +| الحقل | النوع | ما الذي يعنيه | +| ------------- | ----------- | -------------------------------------- | +| `label` | `string` | تسمية الحقل الموجهة للمستخدم. | +| `help` | `string` | نص مساعد قصير. | +| `tags` | `string[]` | وسوم واجهة مستخدم اختيارية. | +| `advanced` | `boolean` | يحدد الحقل على أنه متقدم. | +| `sensitive` | `boolean` | يحدد الحقل على أنه سري أو حساس. | +| `placeholder` | `string` | نص العنصر النائب لمدخلات النماذج. | ## مرجع `contracts` -استخدم `contracts` فقط لبيانات ملكية الإمكانات الثابتة التي يستطيع OpenClaw -قراءتها من دون استيراد وقت تشغيل plugin. +استخدم `contracts` فقط لبيانات تعريف ملكية القدرات الثابتة التي يمكن لـ OpenClaw +قراءتها من دون استيراد وقت تشغيل المكون الإضافي. ```json { @@ -264,21 +342,21 @@ x-i18n: كل قائمة اختيارية: -| الحقل | النوع | معناه | -| -------------------------------- | ---------- | --------------------------------------------------------- | -| `speechProviders` | `string[]` | معرّفات مزودي الكلام التي يملكها هذا plugin. | -| `realtimeTranscriptionProviders` | `string[]` | معرّفات مزودي النسخ الفوري التي يملكها هذا plugin. | -| `realtimeVoiceProviders` | `string[]` | معرّفات مزودي الصوت الفوري التي يملكها هذا plugin. | -| `mediaUnderstandingProviders` | `string[]` | معرّفات مزودي فهم الوسائط التي يملكها هذا plugin. | -| `imageGenerationProviders` | `string[]` | معرّفات مزودي توليد الصور التي يملكها هذا plugin. | -| `videoGenerationProviders` | `string[]` | معرّفات مزودي توليد الفيديو التي يملكها هذا plugin. | -| `webFetchProviders` | `string[]` | معرّفات مزودي web-fetch التي يملكها هذا plugin. | -| `webSearchProviders` | `string[]` | معرّفات مزودي web search التي يملكها هذا plugin. | -| `tools` | `string[]` | أسماء أدوات الوكيل التي يملكها هذا plugin لفحوصات العقود المجمعة. | +| الحقل | النوع | ما الذي يعنيه | +| -------------------------------- | ----------- | -------------------------------------------------------------- | +| `speechProviders` | `string[]` | معرّفات موفري speech التي يملكها هذا المكون الإضافي. | +| `realtimeTranscriptionProviders` | `string[]` | معرّفات موفري realtime transcription التي يملكها هذا المكون الإضافي. | +| `realtimeVoiceProviders` | `string[]` | معرّفات موفري realtime voice التي يملكها هذا المكون الإضافي. | +| `mediaUnderstandingProviders` | `string[]` | معرّفات موفري media-understanding التي يملكها هذا المكون الإضافي. | +| `imageGenerationProviders` | `string[]` | معرّفات موفري image-generation التي يملكها هذا المكون الإضافي. | +| `videoGenerationProviders` | `string[]` | معرّفات موفري video-generation التي يملكها هذا المكون الإضافي. | +| `webFetchProviders` | `string[]` | معرّفات موفري web-fetch التي يملكها هذا المكون الإضافي. | +| `webSearchProviders` | `string[]` | معرّفات موفري web search التي يملكها هذا المكون الإضافي. | +| `tools` | `string[]` | أسماء أدوات الوكيل التي يملكها هذا المكون الإضافي من أجل فحوصات العقد المضمّنة. | ## مرجع `channelConfigs` -استخدم `channelConfigs` عندما يحتاج plugin قناة إلى بيانات إعدادات بسيطة قبل +استخدم `channelConfigs` عندما يحتاج مكون إضافي للقنوات إلى بيانات تعريف تكوين منخفضة التكلفة قبل تحميل وقت التشغيل. ```json @@ -294,33 +372,33 @@ x-i18n: }, "uiHints": { "homeserverUrl": { - "label": "عنوان URL للخادم المنزلي", + "label": "Homeserver URL", "placeholder": "https://matrix.example.com" } }, "label": "Matrix", - "description": "اتصال Matrix homeserver", + "description": "Matrix homeserver connection", "preferOver": ["matrix-legacy"] } } } ``` -يمكن أن يتضمن كل إدخال قناة ما يلي: +يمكن أن يتضمن كل إدخال قناة: -| الحقل | النوع | معناه | -| ------------- | ------------------------ | ------------------------------------------------------------------------------------ | -| `schema` | `object` | JSON Schema لـ `channels.`. وهو مطلوب لكل إدخال إعدادات قناة مُعلن عنه. | -| `uiHints` | `Record` | تسميات UI وعناصر نائبة وتلميحات حساسية اختيارية لهذا القسم من إعدادات القناة. | -| `label` | `string` | تسمية القناة المدمجة في أسطح المحدد والفحص عندما لا تكون بيانات وقت التشغيل جاهزة. | -| `description` | `string` | وصف قصير للقناة لأسطح الفحص والفهرس. | -| `preferOver` | `string[]` | معرّفات plugin قديمة أو أقل أولوية ينبغي أن تتفوق عليها هذه القناة في أسطح الاختيار. | +| الحقل | النوع | ما الذي يعنيه | +| ------------- | ------------------------- | ------------------------------------------------------------------------------------------ | +| `schema` | `object` | مخطط JSON لـ `channels.`. وهو مطلوب لكل إدخال تكوين قناة مُعلن. | +| `uiHints` | `Record` | تسميات واجهة مستخدم/عناصر نائبة/تلميحات حساسية اختيارية لذلك القسم من تكوين القناة. | +| `label` | `string` | تسمية القناة المدمجة في أسطح المحدد والفحص عندما لا تكون بيانات وقت التشغيل الوصفية جاهزة. | +| `description` | `string` | وصف قصير للقناة لأسطح الفحص والفهرس. | +| `preferOver` | `string[]` | معرّفات مكونات إضافية قديمة أو أقل أولوية ينبغي أن تتفوق عليها هذه القناة في أسطح الاختيار. | ## مرجع `modelSupport` -استخدم `modelSupport` عندما ينبغي لـ OpenClaw استنتاج plugin المزود الخاص بك من -معرّفات النماذج المختصرة مثل `gpt-5.4` أو `claude-sonnet-4.6` قبل تحميل -وقت تشغيل plugin. +استخدم `modelSupport` عندما ينبغي لـ OpenClaw أن يستنتج مكون الموفر الإضافي الخاص بك من +معرّفات النماذج المختصرة مثل `gpt-5.4` أو `claude-sonnet-4.6` قبل تحميل وقت تشغيل +المكون الإضافي. ```json { @@ -333,74 +411,73 @@ x-i18n: يطبق OpenClaw ترتيب الأولوية التالي: -- تستخدم مراجع `provider/model` الصريحة بيانات البيان الوصفية `providers` الخاصة بالمالك +- تستخدم مراجع `provider/model` الصريحة بيانات تعريف `providers` المملوكة في البيان - تتفوق `modelPatterns` على `modelPrefixes` -- إذا طابق كل من plugin غير مجمّع وplugin مجمّع، فإن plugin - غير المجمّع يفوز -- يتم تجاهل أي غموض متبقٍ إلى أن يحدد المستخدم أو الإعدادات مزودًا +- إذا طابق كل من مكون إضافي غير مضمّن ومكون إضافي مضمّن، فإن المكون الإضافي + غير المضمّن يفوز +- يُتجاهل أي غموض متبقٍ حتى يحدد المستخدم أو التكوين موفرًا الحقول: -| الحقل | النوع | معناه | -| --------------- | ---------- | -------------------------------------------------------------------------- | -| `modelPrefixes` | `string[]` | بادئات تتم مطابقتها باستخدام `startsWith` مع معرّفات النماذج المختصرة. | -| `modelPatterns` | `string[]` | مصادر Regex تتم مطابقتها مع معرّفات النماذج المختصرة بعد إزالة لاحقة الملف الشخصي. | +| الحقل | النوع | ما الذي يعنيه | +| --------------- | ----------- | -------------------------------------------------------------------------------- | +| `modelPrefixes` | `string[]` | بادئات تُطابق باستخدام `startsWith` مع معرّفات النماذج المختصرة. | +| `modelPatterns` | `string[]` | مصادر Regex تُطابق مع معرّفات النماذج المختصرة بعد إزالة لاحقة ملف التعريف. | -أصبحت مفاتيح الإمكانات القديمة ذات المستوى الأعلى مهملة. استخدم `openclaw doctor --fix` -لنقل `speechProviders` و`realtimeTranscriptionProviders`، +مفاتيح القدرات القديمة ذات المستوى الأعلى أصبحت مهملة. استخدم `openclaw doctor --fix` من أجل +نقل `speechProviders` و`realtimeTranscriptionProviders`، و`realtimeVoiceProviders` و`mediaUnderstandingProviders`، و`imageGenerationProviders` و`videoGenerationProviders`، -و`webFetchProviders` و`webSearchProviders` إلى `contracts`؛ -إذ لم يعد تحميل البيان العادي يعامل تلك الحقول ذات المستوى الأعلى على أنها -ملكية للإمكانات. +و`webFetchProviders` و`webSearchProviders` إلى `contracts`؛ إذ لم يعد +تحميل البيان العادي يتعامل مع تلك الحقول ذات المستوى الأعلى على أنها +ملكية قدرات. ## البيان مقابل `package.json` -يخدم الملفان غرضين مختلفين: +يؤدي الملفان وظيفتين مختلفتين: -| الملف | استخدمه من أجل | -| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.plugin.json` | الاكتشاف، والتحقق من صحة الإعدادات، وبيانات خيارات المصادقة، وتلميحات UI التي يجب أن تكون موجودة قبل تشغيل كود plugin | -| `package.json` | بيانات npm الوصفية، وتثبيت التبعيات، وكتلة `openclaw` المستخدمة لنقاط الإدخال، أو بوابات التثبيت، أو الإعداد، أو بيانات الفهرس | +| الملف | استخدمه من أجل | +| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | +| `openclaw.plugin.json` | الاكتشاف، والتحقق من صحة التكوين، وبيانات تعريف خيارات المصادقة، وتلميحات واجهة المستخدم التي يجب أن تكون موجودة قبل تشغيل كود المكون الإضافي | +| `package.json` | بيانات npm الوصفية، وتثبيت التبعيات، وكتلة `openclaw` المستخدمة لنقاط الدخول، وحظر التثبيت، والإعداد، أو بيانات تعريف الفهرس | -إذا لم تكن متأكدًا من مكان انتماء جزء من البيانات الوصفية، فاستخدم هذه القاعدة: +إذا لم تكن متأكدًا من مكان وضع جزء من البيانات الوصفية، فاستخدم هذه القاعدة: -- إذا كان يجب على OpenClaw معرفته قبل تحميل كود plugin، فضعه في `openclaw.plugin.json` -- إذا كان يتعلق بالتغليف، أو ملفات الإدخال، أو سلوك تثبيت npm، فضعه في `package.json` +- إذا كان يجب على OpenClaw معرفته قبل تحميل كود المكون الإضافي، فضعه في `openclaw.plugin.json` +- إذا كان متعلقًا بالتغليف، أو ملفات الدخول، أو سلوك تثبيت npm، فضعه في `package.json` ### حقول `package.json` التي تؤثر في الاكتشاف -توجد بعض بيانات plugin الوصفية المقصودة قبل وقت التشغيل في `package.json` ضمن +توجد بعض بيانات تعريف المكونات الإضافية قبل وقت التشغيل عمدًا في `package.json` ضمن كتلة `openclaw` بدلًا من `openclaw.plugin.json`. أمثلة مهمة: -| الحقل | معناه | +| الحقل | ما الذي يعنيه | | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.extensions` | يعرّف نقاط إدخال plugin الأصلية. | -| `openclaw.setupEntry` | نقطة إدخال خفيفة مخصصة للإعداد فقط وتُستخدم أثناء الإعداد الأولي وبدء تشغيل القنوات المؤجل. | -| `openclaw.channel` | بيانات وصفية خفيفة لفهرس القنوات مثل التسميات، ومسارات الوثائق، والأسماء المستعارة، ونصوص الاختيار. | -| `openclaw.channel.configuredState` | بيانات وصفية خفيفة لفاحص الحالة المهيأة يمكنها الإجابة عن سؤال "هل يوجد إعداد قائم يعتمد فقط على البيئة؟" من دون تحميل وقت تشغيل القناة الكامل. | -| `openclaw.channel.persistedAuthState` | بيانات وصفية خفيفة لفاحص المصادقة المحفوظة يمكنها الإجابة عن سؤال "هل يوجد أي تسجيل دخول قائم بالفعل؟" من دون تحميل وقت تشغيل القناة الكامل. | -| `openclaw.install.npmSpec` / `openclaw.install.localPath` | تلميحات التثبيت/التحديث لـ plugins المجمعة والمنشورة خارجيًا. | -| `openclaw.install.defaultChoice` | مسار التثبيت المفضل عندما تتوفر عدة مصادر للتثبيت. | -| `openclaw.install.minHostVersion` | الحد الأدنى لإصدار مضيف OpenClaw المدعوم، باستخدام حد أدنى semver مثل `>=2026.3.22`. | -| `openclaw.install.allowInvalidConfigRecovery` | يسمح بمسار استرداد ضيق لإعادة تثبيت plugin مجمّع عندما تكون الإعدادات غير صالحة. | -| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | يتيح تحميل أسطح القنوات الخاصة بالإعداد فقط قبل plugin القناة الكامل أثناء بدء التشغيل. | +| `openclaw.extensions` | يعرّف نقاط دخول المكونات الإضافية الأصلية. | +| `openclaw.setupEntry` | نقطة دخول خفيفة مخصصة للإعداد فقط تُستخدم أثناء التهيئة الأولية وبدء تشغيل القنوات المؤجل. | +| `openclaw.channel` | بيانات تعريف خفيفة لفهرس القنوات مثل التسميات، ومسارات الوثائق، والأسماء المستعارة، ونصوص الاختيار. | +| `openclaw.channel.configuredState` | بيانات تعريف خفيفة لفاحص حالة التكوين يمكنها الإجابة عن سؤال "هل يوجد إعداد يعتمد على env فقط بالفعل؟" من دون تحميل وقت تشغيل القناة الكامل. | +| `openclaw.channel.persistedAuthState` | بيانات تعريف خفيفة لفاحص المصادقة المحفوظة يمكنها الإجابة عن سؤال "هل يوجد أي تسجيل دخول بالفعل؟" من دون تحميل وقت تشغيل القناة الكامل. | +| `openclaw.install.npmSpec` / `openclaw.install.localPath` | تلميحات التثبيت/التحديث للمكونات الإضافية المضمّنة والمنشورة خارجيًا. | +| `openclaw.install.defaultChoice` | مسار التثبيت المفضل عند توفر عدة مصادر تثبيت. | +| `openclaw.install.minHostVersion` | الحد الأدنى المدعوم من إصدار مضيف OpenClaw، باستخدام حد أدنى semver مثل `>=2026.3.22`. | +| `openclaw.install.allowInvalidConfigRecovery` | يسمح بمسار استرداد ضيق لإعادة تثبيت المكونات الإضافية المضمّنة عندما يكون التكوين غير صالح. | +| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | يتيح تحميل أسطح القنوات المخصصة للإعداد فقط قبل المكون الإضافي الكامل للقناة أثناء بدء التشغيل. | -يتم فرض `openclaw.install.minHostVersion` أثناء التثبيت وتحميل -سجل البيانات. وتُرفض القيم غير الصالحة؛ أما القيم الأحدث ولكن الصالحة فتجعل -plugin يُتخطى على المضيفين الأقدم. +يُفرض `openclaw.install.minHostVersion` أثناء التثبيت وتحميل سجل +البيان. تُرفض القيم غير الصالحة؛ أما القيم الأحدث ولكن الصالحة فتتجاوز +المكون الإضافي على المضيفين الأقدم. إن `openclaw.install.allowInvalidConfigRecovery` ضيق النطاق عمدًا. فهو -لا يجعل الإعدادات المعطلة العشوائية قابلة للتثبيت. واليوم لا يسمح إلا لعمليات التثبيت -بالتعافي من إخفاقات ترقية محددة في pluginات المجمعة القديمة، مثل مسار plugin مجمّع -مفقود أو إدخال `channels.` قديم لذلك -plugin المجمّع نفسه. أما أخطاء الإعدادات غير المرتبطة فما تزال تمنع التثبيت وتوجه المشغلين -إلى `openclaw doctor --fix`. +لا يجعل التكوينات المعطوبة التعسفية قابلة للتثبيت. في الوقت الحالي، لا يسمح إلا لتدفقات التثبيت +بالتعافي من حالات فشل معينة قديمة لترقية المكونات الإضافية المضمّنة، مثل +مسار مكون إضافي مضمّن مفقود أو إدخال `channels.` قديم لذلك +المكون الإضافي المضمّن نفسه. وما تزال أخطاء التكوين غير المرتبطة تمنع التثبيت وتوجه +المشغلين إلى `openclaw doctor --fix`. -إن `openclaw.channel.persistedAuthState` هو بيانات وصفية للحزمة لوحدة -فاحص صغيرة: +إن `openclaw.channel.persistedAuthState` هو بيانات تعريف الحزمة لوحدة فاحص صغيرة: ```json { @@ -416,12 +493,13 @@ plugin المجمّع نفسه. أما أخطاء الإعدادات غير ال } ``` -استخدمه عندما تحتاج تدفقات الإعداد أو doctor أو الحالة المهيأة إلى -فحص مصادقة بسيط بنعم/لا قبل تحميل plugin القناة الكامل. يجب أن يكون التصدير المستهدف -دالة صغيرة تقرأ الحالة المحفوظة فقط؛ ولا توجهه عبر شريط وقت تشغيل القناة الكامل. +استخدمه عندما تحتاج تدفقات الإعداد أو doctor أو حالة التكوين إلى +تحقق رخيص بنعم/لا من المصادقة قبل تحميل المكون الإضافي الكامل للقناة. يجب أن يكون +التصدير الهدف دالة صغيرة تقرأ الحالة المحفوظة فقط؛ لا توجهه عبر شريط +وقت تشغيل القناة الكامل. -يتبع `openclaw.channel.configuredState` الشكل نفسه لفحوصات الحالة المهيأة -البسيطة المعتمدة فقط على البيئة: +يتبع `openclaw.channel.configuredState` البنية نفسها من أجل فحوصات حالة التكوين +الرخيصة المعتمدة على env فقط: ```json { @@ -437,65 +515,65 @@ plugin المجمّع نفسه. أما أخطاء الإعدادات غير ال } ``` -استخدمه عندما تستطيع قناة ما تحديد الحالة المهيأة من البيئة أو من مدخلات صغيرة أخرى -غير مرتبطة بوقت التشغيل. وإذا كان الفحص يحتاج إلى حل كامل للإعدادات أو إلى -وقت تشغيل القناة الفعلي، فأبقِ هذا المنطق في hook -`config.hasConfiguredState` الخاصة بـ plugin بدلًا من ذلك. +استخدمه عندما تتمكن قناة من الإجابة عن حالة التكوين من env أو من مدخلات صغيرة +أخرى غير وقت التشغيل. وإذا كان الفحص يحتاج إلى حل التكوين الكامل أو إلى +وقت تشغيل القناة الحقيقي، فأبقِ هذا المنطق في hook +`config.hasConfiguredState` الخاص بالمكون الإضافي بدلًا من ذلك. -## متطلبات JSON Schema +## متطلبات مخطط JSON -- **يجب على كل plugin أن يوفّر JSON Schema**، حتى إذا كان لا يقبل أي إعدادات. -- يُقبل مخطط فارغ (مثلًا `{ "type": "object", "additionalProperties": false }`). -- يتم التحقق من المخططات وقت قراءة/كتابة الإعدادات، وليس وقت التشغيل. +- **يجب على كل مكون إضافي أن يتضمن مخطط JSON**، حتى إذا كان لا يقبل أي تكوين. +- يُقبل مخطط فارغ (على سبيل المثال، `{ "type": "object", "additionalProperties": false }`). +- يتم التحقق من المخططات عند قراءة/كتابة التكوين، وليس أثناء وقت التشغيل. ## سلوك التحقق -- تُعد مفاتيح `channels.*` غير المعروفة **أخطاء**، إلا إذا كان معرّف القناة مُعلنًا من خلال - بيان plugin. +- تُعد مفاتيح `channels.*` غير المعروفة **أخطاء**، ما لم يكن معرّف القناة معلنًا بواسطة + بيان مكون إضافي. - يجب أن تشير `plugins.entries.` و`plugins.allow` و`plugins.deny` و`plugins.slots.*` - إلى معرّفات plugin **قابلة للاكتشاف**. وتُعد المعرّفات غير المعروفة **أخطاء**. -- إذا كان plugin مثبتًا ولكن بيانه أو مخططه معطّلًا أو مفقودًا، - يفشل التحقق ويبلّغ Doctor عن خطأ plugin. -- إذا وُجدت إعدادات plugin لكن plugin **معطّل**، فسيتم الاحتفاظ بالإعدادات - وسيظهر **تحذير** في Doctor + السجلات. + إلى معرّفات مكونات إضافية **قابلة للاكتشاف**. تُعد المعرّفات غير المعروفة **أخطاء**. +- إذا كان المكون الإضافي مثبتًا لكن بيانه أو مخططه معطوبًا أو مفقودًا، + يفشل التحقق ويبلغ Doctor عن خطأ المكون الإضافي. +- إذا كان تكوين المكون الإضافي موجودًا لكن المكون الإضافي **معطل**، فيُحتفظ بالتكوين + وتظهر **تحذيرات** في Doctor + السجلات. -راجع [مرجع الإعدادات](/ar/gateway/configuration) للحصول على مخطط `plugins.*` الكامل. +راجع [مرجع التكوين](/ar/gateway/configuration) للاطلاع على مخطط `plugins.*` الكامل. ## ملاحظات -- البيان **مطلوب لـ plugins OpenClaw الأصلية**، بما في ذلك التحميلات المحلية من نظام الملفات. -- ما يزال وقت التشغيل يحمّل وحدة plugin بشكل منفصل؛ والبيان مخصص فقط لـ - الاكتشاف + التحقق. -- تُحلل البيانات الأصلية باستخدام JSON5، لذلك تُقبل التعليقات والفواصل اللاحقة - والمفاتيح غير المقتبسة ما دامت القيمة النهائية لا تزال كائنًا. -- لا يقرأ محمل البيان إلا حقول البيان الموثقة. تجنب إضافة +- البيان **مطلوب للمكونات الإضافية الأصلية في OpenClaw**، بما في ذلك التحميلات المحلية من نظام الملفات. +- ما يزال وقت التشغيل يحمّل وحدة المكون الإضافي بشكل منفصل؛ البيان مخصص فقط + للاكتشاف + التحقق. +- تُحلَّل البيانات الأصلية باستخدام JSON5، لذا تُقبل التعليقات والفواصل اللاحقة والمفاتيح + غير الموضوعة بين علامتي اقتباس طالما أن القيمة النهائية لا تزال كائنًا. +- لا يقرأ محمّل البيان إلا حقول البيان الموثقة. تجنب إضافة مفاتيح مخصصة ذات مستوى أعلى هنا. -- `providerAuthEnvVars` هو مسار البيانات الوصفية البسيط لفحوصات المصادقة، والتحقق من - علامات env، وأسحط مصادقة المزود المماثلة التي لا ينبغي أن تشغّل وقت تشغيل plugin - فقط لفحص أسماء env. -- يتيح `providerAuthAliases` لمتغيرات المزود إعادة استخدام مصادقة مزود آخر - env vars وملفات تعريف المصادقة والمصادقة المعتمدة على الإعدادات وخيار الإعداد الأولي لمفتاح API - من دون ترميز هذه العلاقة بشكل ثابت داخل النواة. -- `channelEnvVars` هو مسار البيانات الوصفية البسيط للرجوع إلى shell-env، ولمطالبات الإعداد، - وأسحط القنوات المماثلة التي لا ينبغي أن تشغّل وقت تشغيل plugin - فقط لفحص أسماء env. -- `providerAuthChoices` هو مسار البيانات الوصفية البسيط لمحددات خيارات المصادقة، - وحل `--auth-choice`، وربط المزود المفضل، وتسجيل أعلام CLI البسيطة في الإعداد الأولي - قبل تحميل وقت تشغيل المزود. أما بيانات المعالج الإرشادي وقت التشغيل - التي تتطلب كود المزود، فراجع - [hooks وقت تشغيل المزود](/ar/plugins/architecture#provider-runtime-hooks). -- تُختار أنواع plugin الحصرية من خلال `plugins.slots.*`. - - يتم اختيار `kind: "memory"` بواسطة `plugins.slots.memory`. - - يتم اختيار `kind: "context-engine"` بواسطة `plugins.slots.contextEngine` +- `providerAuthEnvVars` هو مسار البيانات الوصفية الرخيص لفحوصات المصادقة، والتحقق من علامات env، + وأسُطح مصادقة الموفر المشابهة التي يجب ألا تشغّل وقت تشغيل المكون الإضافي + لمجرد فحص أسماء env. +- يسمح `providerAuthAliases` لمتغيرات الموفر بإعادة استخدام متغيرات البيئة الخاصة بمصادقة موفر آخر، + وملفات تعريف المصادقة، والمصادقة المستندة إلى التكوين، وخيار الإعداد الأولي + لمفتاح API من دون ترميز ثابت لهذه العلاقة في النواة. +- `channelEnvVars` هو مسار البيانات الوصفية الرخيص للرجوع إلى shell-env، ومطالبات الإعداد، + وأسُطح القنوات المشابهة التي يجب ألا تشغّل وقت تشغيل المكون الإضافي + لمجرد فحص أسماء env. +- `providerAuthChoices` هو مسار البيانات الوصفية الرخيص لمحددات خيارات المصادقة، + وحل `--auth-choice`، وربط الموفر المفضل، وتسجيل أعلام CLI البسيطة في الإعداد الأولي + قبل تحميل وقت تشغيل الموفر. أما بالنسبة إلى بيانات تعريف المعالج التفاعلي في وقت التشغيل + التي تتطلب كود الموفر، فراجع + [hooks وقت تشغيل الموفر](/ar/plugins/architecture#provider-runtime-hooks). +- تُختار أنواع المكونات الإضافية الحصرية عبر `plugins.slots.*`. + - يُختار `kind: "memory"` بواسطة `plugins.slots.memory`. + - يُختار `kind: "context-engine"` بواسطة `plugins.slots.contextEngine` (الافتراضي: `legacy` المدمج). - يمكن حذف `channels` و`providers` و`cliBackends` و`skills` عندما لا - يحتاجها plugin. -- إذا كان plugin الخاص بك يعتمد على وحدات أصلية، فوثّق خطوات البناء وأي - متطلبات لقائمة السماح الخاصة بمدير الحزم (مثل pnpm `allow-build-scripts` + يحتاجها المكون الإضافي. +- إذا كان المكون الإضافي يعتمد على وحدات أصلية، فوثّق خطوات البناء وأي + متطلبات قائمة سماح لمدير الحزم (على سبيل المثال، pnpm `allow-build-scripts` - `pnpm rebuild `). ## ذو صلة -- [بناء Plugins](/ar/plugins/building-plugins) — البدء باستخدام plugins -- [بنية Plugins](/ar/plugins/architecture) — البنية الداخلية +- [بناء المكونات الإضافية](/ar/plugins/building-plugins) — البدء باستخدام المكونات الإضافية +- [بنية المكونات الإضافية](/ar/plugins/architecture) — البنية الداخلية - [نظرة عامة على SDK](/ar/plugins/sdk-overview) — مرجع Plugin SDK diff --git a/docs/ar/reference/rich-output-protocol.md b/docs/ar/reference/rich-output-protocol.md new file mode 100644 index 000000000..16165bf50 --- /dev/null +++ b/docs/ar/reference/rich-output-protocol.md @@ -0,0 +1,60 @@ +--- +x-i18n: + generated_at: "2026-04-11T15:15:51Z" + model: gpt-5.4 + provider: openai + source_hash: 2a8884fc2c304bf96d4675f0c1d1ff781d6dc1ae8c49d92ce08040c9c7709035 + source_path: reference/rich-output-protocol.md + workflow: 15 +--- + +# بروتوكول الإخراج المنسق + +يمكن أن يتضمن إخراج المساعد مجموعة صغيرة من توجيهات التسليم/العرض: + +- ‏`MEDIA:` لتسليم المرفقات +- ‏`[[audio_as_voice]]` لتلميحات العرض الصوتي +- ‏`[[reply_to_current]]` / ‏`[[reply_to:]]` لبيانات الرد الوصفية +- ‏`[embed ...]` للعرض المنسق في واجهة التحكم + +هذه التوجيهات منفصلة. تظل وسوم `MEDIA:` والرد/الصوت بيانات وصفية للتسليم؛ أما `[embed ...]` فهو مسار العرض المنسق الخاص بالويب فقط. + +## ‏`[embed ...]` + +‏`[embed ...]` هو صياغة العرض المنسق الوحيدة الموجهة للوكلاء في واجهة التحكم. + +مثال ذاتي الإغلاق: + +```text +[embed ref="cv_123" title="Status" /] +``` + +القواعد: + +- لم يعد `[view ...]` صالحًا للمخرجات الجديدة. +- تُعرض الشيفرات المختصرة للتضمين في سطح رسالة المساعد فقط. +- لا تُعرض إلا التضمينات المدعومة بعنوان URL. استخدم `ref="..."` أو `url="..."`. +- لا يتم عرض الشيفرات المختصرة المضمنة بصيغة HTML المضمنة على شكل كتلة. +- تقوم واجهة الويب بإزالة الشيفرة المختصرة من النص المرئي وتعرض التضمين ضمنيًا. +- ‏`MEDIA:` ليس اسمًا بديلًا للتضمين، ويجب عدم استخدامه لعرض التضمين المنسق. + +## شكل العرض المخزن + +كتلة محتوى المساعد المُطبَّعة/المخزنة هي عنصر `canvas` منظم: + +```json +{ + "type": "canvas", + "preview": { + "kind": "canvas", + "surface": "assistant_message", + "render": "url", + "viewId": "cv_123", + "url": "/__openclaw__/canvas/documents/cv_123/index.html", + "title": "Status", + "preferredHeight": 320 + } +} +``` + +تستخدم كتل العرض المنسق المخزنة/المعروضة شكل `canvas` هذا مباشرة. لا يتم التعرف على `present_view`. diff --git a/docs/ar/tools/video-generation.md b/docs/ar/tools/video-generation.md index 6288c3c7e..5bcb6d0ff 100644 --- a/docs/ar/tools/video-generation.md +++ b/docs/ar/tools/video-generation.md @@ -1,39 +1,39 @@ --- read_when: - - إنشاء مقاطع فيديو عبر الوكيل - - إعداد موفّري ونماذج توليد الفيديو + - إنشاء الفيديوهات عبر الوكيل + - تكوين مزودي ونماذج إنشاء الفيديوهات - فهم معلمات أداة `video_generate` -summary: أنشئ مقاطع فيديو من النصوص أو الصور أو مقاطع الفيديو الموجودة باستخدام 12 واجهة خلفية للموفّرين -title: توليد الفيديو +summary: أنشئ مقاطع فيديو من النصوص أو الصور أو مقاطع الفيديو الموجودة باستخدام 14 واجهة مزود. +title: إنشاء الفيديوهات x-i18n: - generated_at: "2026-04-11T02:48:47Z" + generated_at: "2026-04-11T15:16:03Z" model: gpt-5.4 provider: openai - source_hash: 6848d03ef578181902517d068e8d9fe2f845e572a90481bbdf7bd9f1c591f245 + source_hash: 0ec159a0bbb6b8a030e68828c0a8bcaf40c8538ecf98bc8ff609dab9d0068263 source_path: tools/video-generation.md workflow: 15 --- -# توليد الفيديو +# إنشاء الفيديوهات -يمكن لوكلاء OpenClaw إنشاء مقاطع فيديو من مطالبات نصية، أو صور مرجعية، أو مقاطع فيديو موجودة. هناك اثنتا عشرة واجهة خلفية للموفّرين مدعومة، ولكل منها خيارات نماذج مختلفة، وأوضاع إدخال، ومجموعات ميزات. يختار الوكيل الموفّر المناسب تلقائيًا بناءً على إعدادك ومفاتيح API المتاحة. +يمكن لوكلاء OpenClaw إنشاء مقاطع فيديو من المطالبات النصية أو الصور المرجعية أو مقاطع الفيديو الموجودة. يتم دعم أربع عشرة واجهة مزود، ولكل منها خيارات نماذج وأوضاع إدخال ومجموعات ميزات مختلفة. يختار الوكيل المزود المناسب تلقائيًا استنادًا إلى تكوينك ومفاتيح API المتاحة. -لا تظهر أداة `video_generate` إلا عندما يكون موفّر واحد على الأقل لتوليد الفيديو متاحًا. إذا لم ترها ضمن أدوات الوكيل لديك، فاضبط مفتاح API لموفّر أو قم بإعداد `agents.defaults.videoGenerationModel`. +لا تظهر أداة `video_generate` إلا عند توفر مزود واحد على الأقل لإنشاء الفيديوهات. إذا لم تظهر ضمن أدوات الوكيل لديك، فقم بتعيين مفتاح API للمزود أو كوّن `agents.defaults.videoGenerationModel`. -يتعامل OpenClaw مع توليد الفيديو باعتباره ثلاثة أوضاع لبيئة التشغيل: +يتعامل OpenClaw مع إنشاء الفيديوهات على أنه ثلاثة أوضاع تشغيل: -- `generate` لطلبات تحويل النص إلى فيديو من دون وسائط مرجعية +- `generate` لطلبات تحويل النص إلى فيديو بدون وسائط مرجعية - `imageToVideo` عندما يتضمن الطلب صورة مرجعية واحدة أو أكثر - `videoToVideo` عندما يتضمن الطلب مقطع فيديو مرجعيًا واحدًا أو أكثر -يمكن للموفّرين دعم أي مجموعة فرعية من هذه الأوضاع. تتحقق الأداة من صحة -الوضع النشط قبل الإرسال وتبلّغ عن الأوضاع المدعومة في `action=list`. +يمكن للمزودين دعم أي مجموعة فرعية من هذه الأوضاع. تتحقق الأداة من الوضع +النشط قبل الإرسال وتعرض الأوضاع المدعومة في `action=list`. -## بدء سريع +## البدء السريع -1. اضبط مفتاح API لأي موفّر مدعوم: +1. عيّن مفتاح API لأي مزود مدعوم: ```bash export GEMINI_API_KEY="your-key" @@ -47,33 +47,33 @@ openclaw config set agents.defaults.videoGenerationModel.primary "google/veo-3.1 3. اطلب من الوكيل: -> أنشئ مقطع فيديو سينمائيًا مدته 5 ثوانٍ لكركند ودود يركب الأمواج عند الغروب. +> أنشئ فيديو سينمائيًا مدته 5 ثوانٍ لكركند ودود يتزلج على الأمواج عند غروب الشمس. سيستدعي الوكيل `video_generate` تلقائيًا. لا حاجة إلى قائمة سماح للأدوات. -## ماذا يحدث عندما تنشئ مقطع فيديو +## ماذا يحدث عند إنشاء فيديو -توليد الفيديو غير متزامن. عندما يستدعي الوكيل `video_generate` في جلسة ما: +إنشاء الفيديو عملية غير متزامنة. عندما يستدعي الوكيل `video_generate` في جلسة: -1. يرسل OpenClaw الطلب إلى الموفّر ويعيد فورًا معرّف مهمة. -2. يعالج الموفّر المهمة في الخلفية (عادةً من 30 ثانية إلى 5 دقائق بحسب الموفّر والدقة). -3. عندما يصبح الفيديو جاهزًا، يوقظ OpenClaw الجلسة نفسها بحدث إكمال داخلي. +1. يرسل OpenClaw الطلب إلى المزود ويعيد فورًا معرّف مهمة. +2. يعالج المزود المهمة في الخلفية (عادةً من 30 ثانية إلى 5 دقائق حسب المزود والدقة). +3. عندما يصبح الفيديو جاهزًا، يوقظ OpenClaw الجلسة نفسها عبر حدث إكمال داخلي. 4. ينشر الوكيل الفيديو النهائي مرة أخرى في المحادثة الأصلية. -أثناء وجود مهمة قيد التنفيذ، تعيد استدعاءات `video_generate` المكررة في الجلسة نفسها حالة المهمة الحالية بدلًا من بدء عملية توليد أخرى. استخدم `openclaw tasks list` أو `openclaw tasks show ` للتحقق من التقدم من CLI. +أثناء تنفيذ المهمة، فإن أي استدعاءات مكررة لـ `video_generate` في الجلسة نفسها تعيد حالة المهمة الحالية بدلًا من بدء إنشاء جديد. استخدم `openclaw tasks list` أو `openclaw tasks show ` للتحقق من التقدم من خلال CLI. -خارج تشغيلات الوكيل المعتمدة على الجلسة (على سبيل المثال، الاستدعاءات المباشرة للأداة)، تعود الأداة إلى التوليد المضمّن وتعيد مسار الوسائط النهائي في الجولة نفسها. +خارج عمليات تشغيل الوكيل المدعومة بجلسة (على سبيل المثال، استدعاءات الأدوات المباشرة)، تعود الأداة إلى الإنشاء المضمن وتعيد مسار الوسائط النهائي في نفس الدورة. ### دورة حياة المهمة -ينتقل كل طلب `video_generate` عبر أربع حالات: +يمر كل طلب `video_generate` عبر أربع حالات: -1. **queued** -- تم إنشاء المهمة، وهي بانتظار أن يقبلها الموفّر. -2. **running** -- يعالج الموفّر المهمة (عادةً من 30 ثانية إلى 5 دقائق بحسب الموفّر والدقة). +1. **queued** -- تم إنشاء المهمة وهي بانتظار أن يقبلها المزود. +2. **running** -- يعالج المزود المهمة (عادةً من 30 ثانية إلى 5 دقائق حسب المزود والدقة). 3. **succeeded** -- أصبح الفيديو جاهزًا؛ يستيقظ الوكيل وينشره في المحادثة. -4. **failed** -- خطأ من الموفّر أو مهلة؛ يستيقظ الوكيل مع تفاصيل الخطأ. +4. **failed** -- خطأ من المزود أو انتهاء مهلة؛ يستيقظ الوكيل مع تفاصيل الخطأ. -تحقق من الحالة من CLI: +تحقق من الحالة من خلال CLI: ```bash openclaw tasks list @@ -81,118 +81,165 @@ openclaw tasks show openclaw tasks cancel ``` -منع التكرار: إذا كانت هناك مهمة فيديو بالفعل بالحالة `queued` أو `running` للجلسة الحالية، فإن `video_generate` يعيد حالة المهمة الموجودة بدلًا من بدء مهمة جديدة. استخدم `action: "status"` للتحقق صراحةً من دون تشغيل توليد جديد. +منع التكرار: إذا كانت هناك بالفعل مهمة فيديو بالحالة `queued` أو `running` للجلسة الحالية، فستعيد `video_generate` حالة المهمة الموجودة بدلًا من بدء مهمة جديدة. استخدم `action: "status"` للتحقق بشكل صريح بدون تشغيل إنشاء جديد. -## الموفّرون المدعومون +## المزودون المدعومون -| الموفّر | النموذج الافتراضي | نص | مرجع صورة | مرجع فيديو | مفتاح API | -| ------- | -------------------------------- | --- | ----------------- | ---------------- | ---------------------------------------- | -| Alibaba | `wan2.6-t2v` | نعم | نعم (URL بعيد) | نعم (URL بعيد) | `MODELSTUDIO_API_KEY` | -| BytePlus | `seedance-1-0-lite-t2v-250428` | نعم | صورة واحدة | لا | `BYTEPLUS_API_KEY` | -| ComfyUI | `workflow` | نعم | صورة واحدة | لا | `COMFY_API_KEY` أو `COMFY_CLOUD_API_KEY` | -| fal | `fal-ai/minimax/video-01-live` | نعم | صورة واحدة | لا | `FAL_KEY` | -| Google | `veo-3.1-fast-generate-preview` | نعم | صورة واحدة | فيديو واحد | `GEMINI_API_KEY` | -| MiniMax | `MiniMax-Hailuo-2.3` | نعم | صورة واحدة | لا | `MINIMAX_API_KEY` | -| OpenAI | `sora-2` | نعم | صورة واحدة | فيديو واحد | `OPENAI_API_KEY` | -| Qwen | `wan2.6-t2v` | نعم | نعم (URL بعيد) | نعم (URL بعيد) | `QWEN_API_KEY` | -| Runway | `gen4.5` | نعم | صورة واحدة | فيديو واحد | `RUNWAYML_API_SECRET` | -| Together | `Wan-AI/Wan2.2-T2V-A14B` | نعم | صورة واحدة | لا | `TOGETHER_API_KEY` | -| Vydra | `veo3` | نعم | صورة واحدة (`kling`) | لا | `VYDRA_API_KEY` | -| xAI | `grok-imagine-video` | نعم | صورة واحدة | فيديو واحد | `XAI_API_KEY` | +| المزود | النموذج الافتراضي | نص | صورة مرجعية | فيديو مرجعي | مفتاح API | +| ------ | ----------------- | --- | ------------ | ------------ | --------- | +| Alibaba | `wan2.6-t2v` | نعم | نعم (URL بعيد) | نعم (URL بعيد) | `MODELSTUDIO_API_KEY` | +| BytePlus (1.0) | `seedance-1-0-pro-250528` | نعم | حتى صورتين (نماذج I2V فقط؛ الإطار الأول + الأخير) | لا | `BYTEPLUS_API_KEY` | +| BytePlus Seedance 1.5 | `seedance-1-5-pro-251215` | نعم | حتى صورتين (الإطار الأول + الأخير عبر الدور) | لا | `BYTEPLUS_API_KEY` | +| BytePlus Seedance 2.0 | `dreamina-seedance-2-0-260128` | نعم | حتى 9 صور مرجعية | حتى 3 مقاطع فيديو | `BYTEPLUS_API_KEY` | +| ComfyUI | `workflow` | نعم | صورة واحدة | لا | `COMFY_API_KEY` أو `COMFY_CLOUD_API_KEY` | +| fal | `fal-ai/minimax/video-01-live` | نعم | صورة واحدة | لا | `FAL_KEY` | +| Google | `veo-3.1-fast-generate-preview` | نعم | صورة واحدة | مقطع فيديو واحد | `GEMINI_API_KEY` | +| MiniMax | `MiniMax-Hailuo-2.3` | نعم | صورة واحدة | لا | `MINIMAX_API_KEY` | +| OpenAI | `sora-2` | نعم | صورة واحدة | مقطع فيديو واحد | `OPENAI_API_KEY` | +| Qwen | `wan2.6-t2v` | نعم | نعم (URL بعيد) | نعم (URL بعيد) | `QWEN_API_KEY` | +| Runway | `gen4.5` | نعم | صورة واحدة | مقطع فيديو واحد | `RUNWAYML_API_SECRET` | +| Together | `Wan-AI/Wan2.2-T2V-A14B` | نعم | صورة واحدة | لا | `TOGETHER_API_KEY` | +| Vydra | `veo3` | نعم | صورة واحدة (`kling`) | لا | `VYDRA_API_KEY` | +| xAI | `grok-imagine-video` | نعم | صورة واحدة | مقطع فيديو واحد | `XAI_API_KEY` | -تقبل بعض الموفّرين متغيرات env إضافية أو بديلة لمفتاح API. راجع [صفحات الموفّرين](#related) الفردية للحصول على التفاصيل. +تقبل بعض المزودات متغيرات بيئة إضافية أو بديلة لمفاتيح API. راجع [صفحات المزود الفردية](#related) للحصول على التفاصيل. -شغّل `video_generate action=list` لفحص الموفّرين والنماذج وأوضاع -بيئة التشغيل المتاحة وقت التشغيل. +شغّل `video_generate action=list` لفحص المزودات والنماذج +وأوضاع التشغيل المتاحة أثناء وقت التشغيل. ### مصفوفة القدرات المعلنة -هذا هو عقد الأوضاع الصريح الذي تستخدمه `video_generate` واختبارات العقود -والمسح الحي المشترك. +هذا هو عقد الأوضاع الصريح الذي تستخدمه `video_generate` واختبارات العقد +والفحص الحي المشترك. -| الموفّر | `generate` | `imageToVideo` | `videoToVideo` | المسارات الحية المشتركة حاليًا | -| ------- | ---------- | -------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------- | -| Alibaba | نعم | نعم | نعم | `generate` و `imageToVideo`؛ يتم تخطي `videoToVideo` لأن هذا الموفّر يحتاج إلى عناوين URL فيديو بعيدة من نوع `http(s)` | -| BytePlus | نعم | نعم | لا | `generate` و `imageToVideo` | -| ComfyUI | نعم | نعم | لا | ليس ضمن المسح المشترك؛ وتوجد التغطية الخاصة بسير العمل مع اختبارات Comfy | -| fal | نعم | نعم | لا | `generate` و `imageToVideo` | -| Google | نعم | نعم | نعم | `generate` و `imageToVideo`؛ يتم تخطي `videoToVideo` المشترك لأن مسح Gemini/Veo الحالي المعتمد على المخزن المؤقت لا يقبل هذا الإدخال | -| MiniMax | نعم | نعم | لا | `generate` و `imageToVideo` | -| OpenAI | نعم | نعم | نعم | `generate` و `imageToVideo`؛ يتم تخطي `videoToVideo` المشترك لأن هذا المسار الخاص بالمؤسسة/الإدخال يحتاج حاليًا إلى وصول inpaint/remix من جهة الموفّر | -| Qwen | نعم | نعم | نعم | `generate` و `imageToVideo`؛ يتم تخطي `videoToVideo` لأن هذا الموفّر يحتاج إلى عناوين URL فيديو بعيدة من نوع `http(s)` | -| Runway | نعم | نعم | نعم | `generate` و `imageToVideo`؛ لا يعمل `videoToVideo` إلا عندما يكون النموذج المحدد هو `runway/gen4_aleph` | -| Together | نعم | نعم | لا | `generate` و `imageToVideo` | -| Vydra | نعم | نعم | لا | `generate`؛ يتم تخطي `imageToVideo` المشترك لأن `veo3` المضمّن نصي فقط و `kling` المضمّن يتطلب عنوان URL بعيدًا للصورة | -| xAI | نعم | نعم | نعم | `generate` و `imageToVideo`؛ يتم تخطي `videoToVideo` لأن هذا الموفّر يحتاج حاليًا إلى عنوان URL بعيد لملف MP4 | +| المزود | `generate` | `imageToVideo` | `videoToVideo` | مسارات الفحص الحي المشتركة الحالية | +| ------ | ---------- | -------------- | -------------- | ----------------------------------- | +| Alibaba | نعم | نعم | نعم | `generate` و`imageToVideo`؛ تم تخطي `videoToVideo` لأن هذا المزود يتطلب عناوين URL لفيديوهات `http(s)` بعيدة | +| BytePlus | نعم | نعم | لا | `generate` و`imageToVideo` | +| ComfyUI | نعم | نعم | لا | ليس ضمن الفحص المشترك؛ التغطية الخاصة بسير العمل موجودة ضمن اختبارات Comfy | +| fal | نعم | نعم | لا | `generate` و`imageToVideo` | +| Google | نعم | نعم | نعم | `generate` و`imageToVideo`؛ تم تخطي `videoToVideo` المشترك لأن فحص Gemini/Veo الحالي المعتمد على المخزن المؤقت لا يقبل هذا الإدخال | +| MiniMax | نعم | نعم | لا | `generate` و`imageToVideo` | +| OpenAI | نعم | نعم | نعم | `generate` و`imageToVideo`؛ تم تخطي `videoToVideo` المشترك لأن مسار المؤسسة/الإدخال هذا يحتاج حاليًا إلى وصول inpaint/remix من جهة المزود | +| Qwen | نعم | نعم | نعم | `generate` و`imageToVideo`؛ تم تخطي `videoToVideo` لأن هذا المزود يتطلب عناوين URL لفيديوهات `http(s)` بعيدة | +| Runway | نعم | نعم | نعم | `generate` و`imageToVideo`؛ يتم تشغيل `videoToVideo` فقط عندما يكون النموذج المحدد هو `runway/gen4_aleph` | +| Together | نعم | نعم | لا | `generate` و`imageToVideo` | +| Vydra | نعم | نعم | لا | `generate`؛ تم تخطي `imageToVideo` المشترك لأن `veo3` المضمن يدعم النص فقط و`kling` المضمن يتطلب عنوان URL بعيدًا للصورة | +| xAI | نعم | نعم | نعم | `generate` و`imageToVideo`؛ تم تخطي `videoToVideo` لأن هذا المزود يتطلب حاليًا عنوان URL بعيدًا لملف MP4 | ## معلمات الأداة ### مطلوبة -| المعلمة | النوع | الوصف | -| ------- | ------ | ---------------------------------------------------------------------------- | -| `prompt` | string | وصف نصي للفيديو المراد إنشاؤه (مطلوب من أجل `action: "generate"`) | +| المعلمة | النوع | الوصف | +| ------- | ----- | ------ | +| `prompt` | string | وصف نصي للفيديو المراد إنشاؤه (مطلوب لـ `action: "generate"`) | ### مدخلات المحتوى -| المعلمة | النوع | الوصف | -| ------- | -------- | ------------------------------------- | -| `image` | string | صورة مرجعية واحدة (مسار أو URL) | -| `images` | string[] | عدة صور مرجعية (حتى 5) | -| `video` | string | فيديو مرجعي واحد (مسار أو URL) | -| `videos` | string[] | عدة مقاطع فيديو مرجعية (حتى 4) | +| المعلمة | النوع | الوصف | +| ------- | ----- | ------ | +| `image` | string | صورة مرجعية واحدة (مسار أو URL) | +| `images` | string[] | صور مرجعية متعددة (حتى 9) | +| `imageRoles` | string[] | تلميحات أدوار اختيارية لكل موضع بالتوازي مع قائمة الصور المدمجة. القيم القياسية: `first_frame` و`last_frame` و`reference_image` | +| `video` | string | مقطع فيديو مرجعي واحد (مسار أو URL) | +| `videos` | string[] | مقاطع فيديو مرجعية متعددة (حتى 4) | +| `videoRoles` | string[] | تلميحات أدوار اختيارية لكل موضع بالتوازي مع قائمة الفيديوهات المدمجة. القيمة القياسية: `reference_video` | +| `audioRef` | string | ملف صوت مرجعي واحد (مسار أو URL). يُستخدم مثلًا للموسيقى الخلفية أو مرجع الصوت عندما يدعم المزود مدخلات الصوت | +| `audioRefs` | string[] | ملفات صوت مرجعية متعددة (حتى 3) | +| `audioRoles` | string[] | تلميحات أدوار اختيارية لكل موضع بالتوازي مع قائمة المقاطع الصوتية المدمجة. القيمة القياسية: `reference_audio` | + +تُمرَّر تلميحات الأدوار إلى المزود كما هي. تأتي القيم القياسية من +اتحاد `VideoGenerationAssetRole` ولكن قد تقبل المزودات +سلاسل أدوار إضافية. يجب ألا تحتوي مصفوفات `*Roles` على عدد إدخالات أكبر من +القائمة المرجعية المقابلة؛ وتفشل أخطاء الزيادة أو النقصان بمقدار واحد برسالة خطأ واضحة. +استخدم سلسلة فارغة لترك خانة بدون تعيين. ### عناصر التحكم في النمط -| المعلمة | النوع | الوصف | -| ---------------- | ------- | ------------------------------------------------------------------------ | -| `aspectRatio` | string | `1:1` أو `2:3` أو `3:2` أو `3:4` أو `4:3` أو `4:5` أو `5:4` أو `9:16` أو `16:9` أو `21:9` | -| `resolution` | string | `480P` أو `720P` أو `768P` أو `1080P` | -| `durationSeconds` | number | المدة المستهدفة بالثواني (تُقرَّب إلى أقرب قيمة يدعمها الموفّر) | -| `size` | string | تلميح للحجم عندما يدعمه الموفّر | -| `audio` | boolean | تفعيل الصوت المُنشأ عند دعمه | -| `watermark` | boolean | تبديل العلامة المائية الخاصة بالموفّر عند دعمها | +| المعلمة | النوع | الوصف | +| ------- | ----- | ------ | +| `aspectRatio` | string | `1:1` أو `2:3` أو `3:2` أو `3:4` أو `4:3` أو `4:5` أو `5:4` أو `9:16` أو `16:9` أو `21:9` أو `adaptive` | +| `resolution` | string | `480P` أو `720P` أو `768P` أو `1080P` | +| `durationSeconds` | number | المدة المستهدفة بالثواني (تُقرَّب إلى أقرب قيمة يدعمها المزود) | +| `size` | string | تلميح للحجم عندما يدعمه المزود | +| `audio` | boolean | تمكين الصوت المُنشأ في الناتج عندما يكون مدعومًا. وهو مختلف عن `audioRef*` (المدخلات) | +| `watermark` | boolean | تبديل العلامة المائية الخاصة بالمزود عندما تكون مدعومة | + +تُعد `adaptive` قيمة خاصة مرتبطة بالمزود: حيث تُمرَّر كما هي إلى +المزودين الذين يعلنون `adaptive` ضمن قدراتهم (على سبيل المثال، يستخدمها BytePlus +Seedance لاكتشاف النسبة تلقائيًا من أبعاد +الصورة المدخلة). أما المزودون الذين لا يعلنون عنها فيعرضون هذه القيمة عبر +`details.ignoredOverrides` في نتيجة الأداة بحيث يكون تجاهلها ظاهرًا. ### متقدمة -| المعلمة | النوع | الوصف | -| --------- | ------ | ---------------------------------------------------- | -| `action` | string | `"generate"` (الافتراضي) أو `"status"` أو `"list"` | -| `model` | string | تجاوز الموفّر/النموذج (مثل `runway/gen4.5`) | -| `filename` | string | تلميح لاسم ملف الإخراج | +| المعلمة | النوع | الوصف | +| ------- | ----- | ------ | +| `action` | string | `"generate"` (افتراضي) أو `"status"` أو `"list"` | +| `model` | string | تجاوز المزود/النموذج (مثل `runway/gen4.5`) | +| `filename` | string | تلميح لاسم ملف الإخراج | +| `providerOptions` | object | خيارات خاصة بالمزود على شكل كائن JSON (مثل `{"seed": 42, "draft": true}`). تتحقق المزودات التي تعلن مخططًا ذا أنواع محددة من المفاتيح وأنواع القيم؛ أما المفاتيح غير المعروفة أو عدم تطابق الأنواع فيؤديان إلى تخطي المرشح أثناء التبديل الاحتياطي. وتتلقى المزودات التي لا تحتوي على مخطط معلن الخيارات كما هي. شغّل `video_generate action=list` لمعرفة ما يقبله كل مزود | -لا تدعم جميع الموفّرين جميع المعلمات. يقوم OpenClaw بالفعل بتطبيع المدة إلى أقرب قيمة يدعمها الموفّر، كما يعيد تعيين تلميحات الهندسة المترجمة مثل تحويل الحجم إلى نسبة أبعاد عندما يكشف موفّر احتياطي عن سطح تحكم مختلف. أما التجاوزات غير المدعومة فعلًا فيتم تجاهلها على أساس أفضل جهد ممكن وتُبلّغ كتحذيرات في نتيجة الأداة. وتفشل حدود القدرات الصارمة (مثل وجود عدد كبير جدًا من المدخلات المرجعية) قبل الإرسال. +لا تدعم جميع المزودات كل المعلمات. يقوم OpenClaw بالفعل بتطبيع المدة إلى أقرب قيمة يدعمها المزود، كما يعيد أيضًا تعيين تلميحات الهندسة المترجمة مثل تحويل الحجم إلى نسبة أبعاد عندما يكشف مزود احتياطي سطح تحكم مختلفًا. أما التجاوزات غير المدعومة فعلًا فيتم تجاهلها بأفضل جهد ممكن والإبلاغ عنها كتحذيرات في نتيجة الأداة. وتفشل حدود القدرات الصارمة (مثل كثرة عدد المدخلات المرجعية) قبل الإرسال. -تُبلّغ نتائج الأداة عن الإعدادات المطبّقة. وعندما يعيد OpenClaw تعيين المدة أو الهندسة أثناء الرجوع إلى موفّر احتياطي، فإن القيم المعادة `durationSeconds` و `size` و `aspectRatio` و `resolution` تعكس ما تم إرساله، ويلتقط `details.normalization` التحويل من المطلوب إلى المطبّق. +تعرض نتائج الأداة الإعدادات المطبقة. عندما يعيد OpenClaw تعيين المدة أو الهندسة أثناء التبديل الاحتياطي بين المزودات، فإن القيم المعادة في `durationSeconds` و`size` و`aspectRatio` و`resolution` تعكس ما تم إرساله، بينما يلتقط `details.normalization` التحويل من القيم المطلوبة إلى القيم المطبقة. -كما تحدد المدخلات المرجعية وضع بيئة التشغيل: +تحدد المدخلات المرجعية أيضًا وضع التشغيل: -- لا توجد وسائط مرجعية: `generate` -- أي مرجع صورة: `imageToVideo` -- أي مرجع فيديو: `videoToVideo` +- بدون وسائط مرجعية: `generate` +- أي صورة مرجعية: `imageToVideo` +- أي فيديو مرجعي: `videoToVideo` +- لا تغيّر المدخلات الصوتية المرجعية الوضع الذي تم تحديده؛ بل تُطبَّق فوق أي وضع تحدده المراجع الصورية/الفيديوية، ولا تعمل إلا مع المزودات التي تعلن `maxInputAudios` -لا يُعد خلط مراجع الصور والفيديو سطح قدرات مشتركًا ومستقرًا. -يُفضّل استخدام نوع مرجعي واحد لكل طلب. +إن المزج بين مراجع الصور والفيديو ليس سطح قدرات مشتركة مستقرًا. +يُفضَّل استخدام نوع مرجعي واحد لكل طلب. + +#### التبديل الاحتياطي والخيارات ذات الأنواع المحددة + +تُطبَّق بعض فحوصات القدرات في طبقة التبديل الاحتياطي بدلًا من +حدود الأداة حتى يتمكن الطلب الذي يتجاوز حدود المزود الأساسي +من العمل على مزود احتياطي قادر: + +- إذا لم يعلن المرشح النشط عن `maxInputAudios` (أو أعلن عنها على أنها + `0`)، فسيتم تخطيه عندما يحتوي الطلب على مراجع صوتية، وتتم + تجربة المرشح التالي. +- إذا كانت `maxDurationSeconds` لدى المرشح النشط أقل من + `durationSeconds` المطلوبة ولم يعلن المرشح عن قائمة + `supportedDurationSeconds`، فسيتم تخطيه. +- إذا كان الطلب يحتوي على `providerOptions` وكان المرشح النشط + يعلن صراحة عن مخطط `providerOptions` ذي أنواع محددة، فسيتم + تخطي المرشح عندما لا تكون المفاتيح الموردة موجودة في المخطط أو عندما + لا تتطابق أنواع القيم. أما المزودات التي لم تعلن عن مخطط بعد فتتلقى + الخيارات كما هي (تمرير متوافق مع الإصدارات السابقة). ويمكن للمزود + إلغاء قبول جميع خيارات المزود صراحة عبر إعلان مخطط فارغ + (`capabilities.providerOptions: {}`)، مما يؤدي إلى نفس التخطي الناتج عن + عدم تطابق النوع. + +يُسجَّل أول سبب للتخطي في الطلب عند مستوى `warn` حتى يرى المشغلون +متى تم تجاوز مزودهم الأساسي؛ أما أسباب التخطي اللاحقة فتُسجَّل عند +`debug` للحفاظ على هدوء سلاسل التبديل الاحتياطي الطويلة. وإذا تم تخطي +كل المرشحين، فسيشمل الخطأ المجمّع سبب التخطي لكل منهم. ## الإجراءات -- **generate** (الافتراضي) -- أنشئ فيديو من المطالبة المعطاة والمدخلات المرجعية الاختيارية. -- **status** -- تحقق من حالة مهمة الفيديو الجاري تنفيذها للجلسة الحالية من دون بدء عملية توليد أخرى. -- **list** -- اعرض الموفّرين والنماذج وقدراتهم المتاحة. +- **generate** (افتراضي) -- إنشاء فيديو من المطالبة المعطاة والمدخلات المرجعية الاختيارية. +- **status** -- التحقق من حالة مهمة الفيديو الجارية للجلسة الحالية دون بدء إنشاء آخر. +- **list** -- عرض المزودات والنماذج المتاحة وقدراتها. ## اختيار النموذج عند إنشاء فيديو، يحل OpenClaw النموذج بهذا الترتيب: -1. **معلمة الأداة `model`** -- إذا حدّدها الوكيل في الاستدعاء. -2. **`videoGenerationModel.primary`** -- من الإعداد. -3. **`videoGenerationModel.fallbacks`** -- تتم تجربتها بالترتيب. -4. **الاكتشاف التلقائي** -- يستخدم الموفّرين الذين لديهم مصادقة صالحة، بدءًا من الموفّر الافتراضي الحالي، ثم بقية الموفّرين بترتيب أبجدي. +1. **معلمة الأداة `model`** -- إذا حددها الوكيل في الاستدعاء. +2. **`videoGenerationModel.primary`** -- من التكوين. +3. **`videoGenerationModel.fallbacks`** -- تُجرَّب بالترتيب. +4. **الاكتشاف التلقائي** -- يستخدم المزودات التي لديها مصادقة صالحة، بدءًا من المزود الافتراضي الحالي، ثم المزودات المتبقية بترتيب أبجدي. -إذا فشل أحد الموفّرين، تتم تجربة المرشح التالي تلقائيًا. وإذا فشل جميع المرشحين، فسيتضمن الخطأ تفاصيل من كل محاولة. +إذا فشل مزود، فسيتم تجربة المرشح التالي تلقائيًا. وإذا فشل جميع المرشحين، فسيتضمن الخطأ تفاصيل من كل محاولة. -اضبط `agents.defaults.mediaGenerationAutoProviderFallback: false` إذا كنت تريد -أن يستخدم توليد الفيديو فقط إدخالات `model` و `primary` و `fallbacks` +عيّن `agents.defaults.mediaGenerationAutoProviderFallback: false` إذا كنت تريد +أن يستخدم إنشاء الفيديو فقط إدخالات `model` و`primary` و`fallbacks` الصريحة. ```json5 @@ -208,56 +255,30 @@ openclaw tasks cancel } ``` -يمكن تثبيت وكيل الفيديو HeyGen على fal باستخدام: +## ملاحظات حول المزودين -```json5 -{ - agents: { - defaults: { - videoGenerationModel: { - primary: "fal/fal-ai/heygen/v2/video-agent", - }, - }, - }, -} -``` +| المزود | ملاحظات | +| ------ | -------- | +| Alibaba | يستخدم نقطة النهاية غير المتزامنة DashScope/Model Studio. يجب أن تكون الصور ومقاطع الفيديو المرجعية عناوين URL بعيدة من نوع `http(s)`. | +| BytePlus (1.0) | معرّف المزود `byteplus`. النماذج: `seedance-1-0-pro-250528` (افتراضي)، و`seedance-1-0-pro-t2v-250528`، و`seedance-1-0-pro-fast-251015`، و`seedance-1-0-lite-t2v-250428`، و`seedance-1-0-lite-i2v-250428`. لا تقبل نماذج T2V (`*-t2v-*`) مدخلات الصور؛ بينما تدعم نماذج I2V ونماذج `*-pro-*` العامة صورة مرجعية واحدة (الإطار الأول). مرّر الصورة موضعيًا أو عيّن `role: "first_frame"`. يتم تبديل معرّفات نماذج T2V تلقائيًا إلى متغير I2V المقابل عند توفير صورة. مفاتيح `providerOptions` المدعومة: `seed` (رقم)، و`draft` (قيمة منطقية، يفرض دقة 480p)، و`camera_fixed` (قيمة منطقية). | +| BytePlus Seedance 1.5 | يتطلب إضافة [`@openclaw/byteplus-modelark`](https://www.npmjs.com/package/@openclaw/byteplus-modelark). معرّف المزود `byteplus-seedance15`. النموذج: `seedance-1-5-pro-251215`. يستخدم واجهة `content[]` الموحدة. يدعم بحد أقصى صورتين مدخلتين (first_frame + last_frame). يجب أن تكون جميع المدخلات عناوين URL بعيدة من نوع `https://`. عيّن `role: "first_frame"` / `"last_frame"` لكل صورة، أو مرّر الصور موضعيًا. يقوم `aspectRatio: "adaptive"` باكتشاف النسبة تلقائيًا من صورة الإدخال. يتم تحويل `audio: true` إلى `generate_audio`. ويتم تمرير `providerOptions.seed` (رقم). | +| BytePlus Seedance 2.0 | يتطلب إضافة [`@openclaw/byteplus-modelark`](https://www.npmjs.com/package/@openclaw/byteplus-modelark). معرّف المزود `byteplus-seedance2`. النماذج: `dreamina-seedance-2-0-260128` و`dreamina-seedance-2-0-fast-260128`. يستخدم واجهة `content[]` الموحدة. يدعم حتى 9 صور مرجعية و3 مقاطع فيديو مرجعية و3 ملفات صوت مرجعية. يجب أن تكون جميع المدخلات عناوين URL بعيدة من نوع `https://`. عيّن `role` لكل أصل — القيم المدعومة: `"first_frame"` و`"last_frame"` و`"reference_image"` و`"reference_video"` و`"reference_audio"`. يقوم `aspectRatio: "adaptive"` باكتشاف النسبة تلقائيًا من صورة الإدخال. يتم تحويل `audio: true` إلى `generate_audio`. ويتم تمرير `providerOptions.seed` (رقم). | +| ComfyUI | تنفيذ محلي أو سحابي قائم على سير العمل. يدعم تحويل النص إلى فيديو وتحويل الصورة إلى فيديو عبر الرسم البياني المكوَّن. | +| fal | يستخدم تدفقًا مدعومًا بالطابور للمهام طويلة التشغيل. يدعم صورة مرجعية واحدة فقط. | +| Google | يستخدم Gemini/Veo. يدعم صورة مرجعية واحدة أو مقطع فيديو مرجعي واحد. | +| MiniMax | يدعم صورة مرجعية واحدة فقط. | +| OpenAI | يتم تمرير تجاوز `size` فقط. ويتم تجاهل تجاوزات النمط الأخرى (`aspectRatio` و`resolution` و`audio` و`watermark`) مع تحذير. | +| Qwen | يستخدم الواجهة الخلفية DashScope نفسها الخاصة بـ Alibaba. يجب أن تكون المدخلات المرجعية عناوين URL بعيدة من نوع `http(s)`؛ ويتم رفض الملفات المحلية مسبقًا. | +| Runway | يدعم الملفات المحلية عبر معرّفات URI للبيانات. يتطلب تحويل الفيديو إلى فيديو `runway/gen4_aleph`. تكشف عمليات التشغيل النصية فقط نسب الأبعاد `16:9` و`9:16`. | +| Together | يدعم صورة مرجعية واحدة فقط. | +| Vydra | يستخدم `https://www.vydra.ai/api/v1` مباشرة لتجنب عمليات إعادة التوجيه التي تُسقط المصادقة. يأتي `veo3` مضمّنًا كنمط تحويل النص إلى فيديو فقط؛ بينما يتطلب `kling` عنوان URL بعيدًا للصورة. | +| xAI | يدعم تحويل النص إلى فيديو، وتحويل الصورة إلى فيديو، وتدفقات تحرير/تمديد الفيديو البعيدة. | -يمكن تثبيت Seedance 2.0 على fal باستخدام: +## أوضاع قدرات المزود -```json5 -{ - agents: { - defaults: { - videoGenerationModel: { - primary: "fal/bytedance/seedance-2.0/fast/text-to-video", - }, - }, - }, -} -``` - -## ملاحظات حول الموفّرين - -| الموفّر | الملاحظات | -| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Alibaba | يستخدم نقطة النهاية غير المتزامنة الخاصة بـ DashScope/Model Studio. يجب أن تكون الصور ومقاطع الفيديو المرجعية عناوين URL بعيدة من نوع `http(s)`. | -| BytePlus | يدعم صورة مرجعية واحدة فقط. | -| ComfyUI | تنفيذ محلي أو سحابي قائم على سير العمل. يدعم تحويل النص إلى فيديو وتحويل الصورة إلى فيديو عبر المخطط المضبوط. | -| fal | يستخدم تدفقًا قائمًا على قائمة انتظار للمهام طويلة التشغيل. يدعم صورة مرجعية واحدة فقط. ويتضمن مراجع النماذج الخاصة بـ HeyGen video-agent و Seedance 2.0 لتحويل النص إلى فيديو وتحويل الصورة إلى فيديو. | -| Google | يستخدم Gemini/Veo. يدعم صورة مرجعية واحدة أو فيديو مرجعيًا واحدًا. | -| MiniMax | يدعم صورة مرجعية واحدة فقط. | -| OpenAI | لا يتم تمرير سوى تجاوز `size`. أما تجاوزات النمط الأخرى (`aspectRatio` و `resolution` و `audio` و `watermark`) فيتم تجاهلها مع تحذير. | -| Qwen | يستخدم الواجهة الخلفية DashScope نفسها الخاصة بـ Alibaba. يجب أن تكون المدخلات المرجعية عناوين URL بعيدة من نوع `http(s)`؛ ويتم رفض الملفات المحلية مقدمًا. | -| Runway | يدعم الملفات المحلية عبر data URIs. يتطلب تحويل الفيديو إلى فيديو `runway/gen4_aleph`. وتعرض التشغيلات النصية فقط نسب أبعاد `16:9` و `9:16`. | -| Together | يدعم صورة مرجعية واحدة فقط. | -| Vydra | يستخدم `https://www.vydra.ai/api/v1` مباشرة لتجنب عمليات إعادة التوجيه التي تُسقط المصادقة. يأتي `veo3` مضمّنًا لتحويل النص إلى فيديو فقط؛ ويتطلب `kling` عنوان URL بعيدًا للصورة. | -| xAI | يدعم تحويل النص إلى فيديو، وتحويل الصورة إلى فيديو، وتدفقات تحرير/تمديد الفيديو البعيد. | - -## أوضاع قدرات الموفّر - -يتيح عقد توليد الفيديو المشترك الآن للموفّرين إعلان قدرات خاصة بكل وضع -بدلًا من الاكتفاء بالحدود المجمّعة المسطحة فقط. ويجب أن تفضّل -تنفيذات الموفّرين الجديدة كتل الأوضاع الصريحة: +يتيح عقد إنشاء الفيديوهات المشترك الآن للمزودات إعلان +قدرات خاصة بكل وضع بدلًا من الاكتفاء بحدود مجمعة مسطحة فقط. ويجب على +التنفيذات الجديدة للمزودات تفضيل كتل الأوضاع الصريحة: ```typescript capabilities: { @@ -281,42 +302,43 @@ capabilities: { } ``` -لا تكفي الحقول المجمّعة المسطحة مثل `maxInputImages` و `maxInputVideos` -للإعلان عن دعم أوضاع التحويل. يجب على الموفّرين أن يعلنوا -`generate` و `imageToVideo` و `videoToVideo` صراحةً حتى تتمكن الاختبارات الحية، -واختبارات العقود، وأداة `video_generate` المشتركة من التحقق من دعم الأوضاع +لا تكفي الحقول المجمعة المسطحة مثل `maxInputImages` و`maxInputVideos` +للإعلان عن دعم أوضاع التحويل. يجب على المزودات إعلان +`generate` و`imageToVideo` و`videoToVideo` بشكل صريح حتى تتمكن الاختبارات الحية +واختبارات العقد وأداة `video_generate` المشتركة من التحقق من دعم الأوضاع بشكل حتمي. ## الاختبارات الحية -تغطية حية اختيارية للموفّرين المضمّنين المشتركين: +تغطية حية اختيارية للمزودات المضمنة المشتركة: ```bash OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts ``` -مغلف المستودع: +مغلّف المستودع: ```bash pnpm test:live:media video ``` -يحمّل هذا الملف الحي متغيرات env الناقصة الخاصة بالموفّر من `~/.profile`، ويفضّل -مفاتيح API الحية/من env على ملفات المصادقة المخزنة افتراضيًا، ويشغّل -الأوضاع المعلنة التي يمكنه اختبارها بأمان باستخدام الوسائط المحلية: +يقوم هذا الملف الحي بتحميل متغيرات بيئة المزودات الناقصة من `~/.profile`، +ويعطي الأفضلية افتراضيًا لمفاتيح API الحية/الخاصة بالبيئة على ملفات +المصادقة المخزنة، ويشغّل الأوضاع المعلنة التي يمكنه اختبارها بأمان باستخدام +وسائط محلية: -- `generate` لكل موفّر في المسح +- `generate` لكل مزود في الفحص - `imageToVideo` عندما تكون `capabilities.imageToVideo.enabled` -- `videoToVideo` عندما تكون `capabilities.videoToVideo.enabled` ويقبل الموفّر/النموذج - إدخال فيديو محليًا مدعومًا بالمخزن المؤقت في المسح المشترك +- `videoToVideo` عندما تكون `capabilities.videoToVideo.enabled` ويقبل المزود/النموذج + إدخال الفيديو المحلي المعتمد على المخزن المؤقت في الفحص المشترك يغطي مسار `videoToVideo` الحي المشترك اليوم: -- `runway` فقط عندما تختار `runway/gen4_aleph` +- `runway` فقط عند اختيار `runway/gen4_aleph` -## الإعداد +## التكوين -اضبط نموذج توليد الفيديو الافتراضي في إعداد OpenClaw الخاص بك: +عيّن نموذج إنشاء الفيديو الافتراضي في تكوين OpenClaw الخاص بك: ```json5 { @@ -337,10 +359,10 @@ pnpm test:live:media video openclaw config set agents.defaults.videoGenerationModel.primary "qwen/wan2.6-t2v" ``` -## ذي صلة +## ذو صلة - [نظرة عامة على الأدوات](/ar/tools) -- [المهام في الخلفية](/ar/automation/tasks) -- تتبع المهام لتوليد الفيديو غير المتزامن +- [المهام في الخلفية](/ar/automation/tasks) -- تتبع المهام لإنشاء الفيديوهات غير المتزامن - [Alibaba Model Studio](/ar/providers/alibaba) - [BytePlus](/ar/concepts/model-providers#byteplus-international) - [ComfyUI](/ar/providers/comfy) @@ -353,5 +375,5 @@ openclaw config set agents.defaults.videoGenerationModel.primary "qwen/wan2.6-t2 - [Together AI](/ar/providers/together) - [Vydra](/ar/providers/vydra) - [xAI](/ar/providers/xai) -- [مرجع الإعداد](/ar/gateway/configuration-reference#agent-defaults) +- [مرجع التكوين](/ar/gateway/configuration-reference#agent-defaults) - [النماذج](/ar/concepts/models)