openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh ar translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-23 14:05:47 +00:00
parent 860615c06f
commit 481b422546
36 changed files with 6480 additions and 8367 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

598
docs/ar/channels/discord.md
View File

File diff suppressed because it is too large Load Diff

68
docs/ar/channels/irc.md
View File

@ -1,14 +1,14 @@
---
read_when:
- تريد توصيل OpenClaw بقنوات IRC أو الرسائل المباشرة
- أنت تقوم بتكوين قوائم السماح في IRC، أو سياسة المجموعات، أو تقييد الإشارات
summary: إعداد Plugin الخاص بـ IRC، وعناصر التحكم في الوصول، واستكشاف الأخطاء وإصلاحها
- تريد توصيل OpenClaw بقنوات IRC أو بالرسائل المباشرة
- أنت تقوم بتكوين قوائم السماح في IRC، أو سياسة المجموعات، أو تقييد الإشارات.
summary: إعداد Plugin ‏IRC، وضوابط الوصول، واستكشاف الأخطاء وإصلاحها
title: IRC
x-i18n:
generated_at: "2026-04-23T07:18:44Z"
generated_at: "2026-04-23T13:58:00Z"
model: gpt-5.4
provider: openai
source_hash: 28d0929e1e3f882eca1ba46eeb5e3fa537baaebfedbe2cf4079946cd9b432c87
source_hash: e198c03db9aaf4ec64db462d44d42aa352a2ddba808bcd29e21eb2791d9755ad
source_path: channels/irc.md
workflow: 15
---
@ -38,7 +38,7 @@ x-i18n:
}
```
يُفضَّل استخدام خادم IRC خاص لتنسيق البوت. إذا كنت تستخدم عمدًا شبكة IRC عامة، فمن الخيارات الشائعة Libera.Chat و OFTC و Snoonet. تجنّب القنوات العامة المتوقعة لحركة المرور الخلفية الخاصة بالبوت أو السرب.
يُفضّل استخدام خادم IRC خاص لتنسيق البوت. إذا كنت تستخدم عمدًا شبكة IRC عامة، فمن الخيارات الشائعة Libera.Chat وOFTC وSnoonet. تجنّب القنوات العامة المتوقعة لحركة المرور الخلفية الخاصة بالبوت أو السرب.
3. ابدأ/أعد تشغيل Gateway:
@ -51,35 +51,35 @@ openclaw gateway run
- القيمة الافتراضية لـ `channels.irc.dmPolicy` هي `"pairing"`.
- القيمة الافتراضية لـ `channels.irc.groupPolicy` هي `"allowlist"`.
- عند استخدام `groupPolicy="allowlist"`، اضبط `channels.irc.groups` لتعريف القنوات المسموح بها.
- استخدم TLS (`channels.irc.tls=true`) ما لم تكن تقبل عمدًا النقل النصي غير المشفر.
- استخدم TLS (`channels.irc.tls=true`) إلا إذا كنت تقبل عمدًا نقلًا نصيًا غير مشفر.
## التحكم في الوصول
هناك «بوابتان» منفصلتان لقنوات IRC:
هناك “بوابتان” منفصلتان لقنوات IRC:
1. **وصول القناة** (`groupPolicy` + `groups`): هل يقبل البوت الرسائل من القناة أساسًا.
2. **وصول المرسل** (`groupAllowFrom` / الإعداد الخاص بكل قناة `groups["#channel"].allowFrom`): من المسموح له بتشغيل البوت داخل تلك القناة.
1. **الوصول إلى القناة** (`groupPolicy` + `groups`): ما إذا كان البوت يقبل الرسائل من القناة أصلًا.
2. **وصول المرسل** (`groupAllowFrom` / `groups["#channel"].allowFrom` لكل قناة): من المسموح له بتفعيل البوت داخل تلك القناة.
مفاتيح التكوين:
- قائمة السماح للرسائل المباشرة (وصول مرسل الرسائل المباشرة): `channels.irc.allowFrom`
- قائمة السماح لمرسلي المجموعات (وصول مرسل القناة): `channels.irc.groupAllowFrom`
- عناصر التحكم لكل قناة (القناة + المرسل + قواعد الإشارة): `channels.irc.groups["#channel"]`
- يتيح `channels.irc.groupPolicy="open"` القنوات غير المضبوطة (**لكنها تظل مقيدة بالإشارة افتراضيًا**)
- يتيح `channels.irc.groupPolicy="open"` القنوات غير المضبوطة (**مع بقاء تقييد الإشارات مفعّلًا افتراضيًا**)
يجب أن تستخدم إدخالات قائمة السماح هويات مرسل ثابتة (`nick!user@host`).
مطابقة الاسم المختصر فقط قابلة للتغير، ولا تُفعَّل إلا عند تعيين `channels.irc.dangerouslyAllowNameMatching: true`.
يجب أن تستخدم عناصر قائمة السماح هويات مرسل ثابتة (`nick!user@host`).
مطابقة الاسم المختصر فقط قابلة للتغيّر ولا تُفعّل إلا عند ضبط `channels.irc.dangerouslyAllowNameMatching: true`.
### مشكلة شائعة: `allowFrom` مخصص للرسائل المباشرة، وليس للقنوات
### ملاحظة شائعة: `allowFrom` مخصّص للرسائل المباشرة وليس للقنوات
إذا رأيت سجلات مثل:
- `irc: drop group sender alice!ident@host (policy=allowlist)`
...فهذا يعني أن المرسل غير مسموح له في رسائل **المجموعة/القناة**. أصلح ذلك إما عبر:
...فهذا يعني أن المرسل غير مسموح له برسائل **المجموعة/القناة**. أصلح ذلك بإحدى الطريقتين:
- تعيين `channels.irc.groupAllowFrom` (عام لكل القنوات)، أو
- تعيين قوائم سماح المرسلين لكل قناة: `channels.irc.groups["#channel"].allowFrom`
- ضبط `channels.irc.groupAllowFrom` (عام لكل القنوات)، أو
- ضبط قوائم سماح المرسلين لكل قناة: `channels.irc.groups["#channel"].allowFrom`
مثال (السماح لأي شخص في `#tuirc-dev` بالتحدث إلى البوت):
@ -98,7 +98,7 @@ openclaw gateway run
## تشغيل الردود (الإشارات)
حتى إذا كانت القناة مسموحًا بها (عبر `groupPolicy` + `groups`) وكان المرسل مسموحًا به، فإن OpenClaw يستخدم افتراضيًا **تقييد الإشارات** في سياقات المجموعات.
حتى إذا كانت القناة مسموحًا بها (عبر `groupPolicy` + `groups`) وكان المرسل مسموحًا به، يستخدم OpenClaw افتراضيًا **تقييد الإشارات** في سياقات المجموعات.
هذا يعني أنك قد ترى سجلات مثل `drop channel … (missing-mention)` ما لم تتضمن الرسالة نمط إشارة يطابق البوت.
@ -120,7 +120,7 @@ openclaw gateway run
}
```
أو للسماح **لكل** قنوات IRC (من دون قائمة سماح لكل قناة) مع الرد أيضًا من دون إشارات:
أو للسماح **بجميع** قنوات IRC (من دون قائمة سماح لكل قناة) مع الرد أيضًا من دون إشارات:
```json5
{
@ -137,8 +137,8 @@ openclaw gateway run
## ملاحظة أمنية (موصى بها للقنوات العامة)
إذا سمحت بـ `allowFrom: ["*"]` في قناة عامة، فيمكن لأي شخص توجيه أوامر إلى البوت.
لتقليل المخاطر، قيّد الأدوات لتلك القناة.
إذا سمحت بـ `allowFrom: ["*"]` في قناة عامة، فسيتمكن أي شخص من توجيه أوامر إلى البوت.
ولتقليل المخاطر، قيّد الأدوات لتلك القناة.
### الأدوات نفسها للجميع في القناة
@ -159,9 +159,9 @@ openclaw gateway run
}
```
### أدوات مختلفة لكل مرسل (المالك يحصل على صلاحيات أكبر)
### أدوات مختلفة حسب المرسل (المالك يحصل على صلاحيات أكبر)
استخدم `toolsBySender` لتطبيق سياسة أشد على `"*"` وسياسة أخف على اسمك:
استخدم `toolsBySender` لتطبيق سياسة أكثر تشددًا على `"*"` وسياسة أخف على اسمك:
```json5
{
@ -189,10 +189,10 @@ openclaw gateway run
- يجب أن تستخدم مفاتيح `toolsBySender` البادئة `id:` لقيم هوية مرسل IRC:
`id:eigen` أو `id:eigen!~eigen@174.127.248.171` لمطابقة أقوى.
- لا تزال المفاتيح القديمة غير المسبوقة ببادئة مقبولة، وتُطابَق بصيغة `id:` فقط.
- تفوز أول سياسة مرسل مطابقة؛ وتكون `"*"` هي المطابقة الاحتياطية العامة.
- لا تزال المفاتيح القديمة غير المسبوقة ببادئة مقبولة وتُطابق بصفتها `id:` فقط.
- أول سياسة مرسل مطابقة هي التي تُطبّق؛ و`"*"` هي الاحتياط العام.
للمزيد حول وصول المجموعات مقابل تقييد الإشارات (وكيفية تفاعلهما)، راجع: [/channels/groups](/ar/channels/groups).
للمزيد حول الوصول إلى المجموعات مقابل تقييد الإشارات (وكيفية تفاعلهما)، راجع: [/channels/groups](/ar/channels/groups).
## NickServ
@ -227,7 +227,7 @@ openclaw gateway run
}
```
عطّل `register` بعد تسجيل الاسم لتجنب محاولات `REGISTER` المتكررة.
عطّل `register` بعد تسجيل الاسم لتجنّب محاولات REGISTER المتكررة.
## متغيرات البيئة
@ -244,19 +244,13 @@ openclaw gateway run
- `IRC_NICKSERV_PASSWORD`
- `IRC_NICKSERV_REGISTER_EMAIL`
<Note>
`IRC_HOST` موجود في قائمة حظر كتل نقاط النهاية ولا يمكن تعيينه من ملف
`.env` في مساحة العمل. يجب أن يأتي من بيئة الصدفة أو من بيئة عملية Gateway
حتى لا تتمكن مساحات العمل غير الموثوقة من إعادة توجيه حركة IRC إلى
خادم مختلف. راجع [ملفات `.env` لمساحة العمل](/ar/gateway/security) للاطلاع على القائمة
الكاملة.
</Note>
لا يمكن تعيين `IRC_HOST` من ملف `.env` خاص بمساحة العمل؛ راجع [ملفات `.env` لمساحة العمل](/ar/gateway/security).
## استكشاف الأخطاء وإصلاحها
- إذا كان البوت يتصل لكنه لا يرد أبدًا في القنوات، فتحقق من `channels.irc.groups` **وكذلك** مما إذا كان تقييد الإشارات يسقط الرسائل (`missing-mention`). إذا كنت تريد أن يرد من دون تنبيهات، فاضبط `requireMention:false` للقناة.
- إذا فشل تسجيل الدخول، فتحقق من توفر الاسم المستعار وكلمة مرور الخادم.
- إذا فشل TLS على شبكة مخصصة، فتحقق من المضيف/المنفذ وإعداد الشهادة.
- إذا كان البوت يتصل لكنه لا يرد أبدًا في القنوات، فتحقق من `channels.irc.groups` **وكذلك** مما إذا كان تقييد الإشارات يُسقط الرسائل (`missing-mention`). إذا كنت تريد أن يرد من دون تنبيهات، فاضبط `requireMention:false` للقناة.
- إذا فشل تسجيل الدخول، فتحقق من توفر الاسم وكلمة مرور الخادم.
- إذا فشل TLS على شبكة مخصصة، فتحقق من إعدادات المضيف/المنفذ والشهادة.
## ذو صلة

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

File diff suppressed because it is too large Load Diff

325
docs/ar/channels/mattermost.md
View File

@ -5,26 +5,26 @@ read_when:
summary: إعداد بوت Mattermost وتكوين OpenClaw
title: Mattermost
x-i18n:
generated_at: "2026-04-23T07:19:04Z"
generated_at: "2026-04-23T13:58:00Z"
model: gpt-5.4
provider: openai
source_hash: 04913fe38ddce73eba2a7f3953ec3241b6871ce4a06e0393d09331e37a39cc2f
source_hash: d9421ae903caed5c9dc3b19ca8558725f11bbe553a20bd4d3f0fb6e7eecccd92
source_path: channels/mattermost.md
workflow: 15
---
# Mattermost
الحالة: Plugin مضمّن (رمز bot token + أحداث WebSocket). القنوات والمجموعات والرسائل الخاصة مدعومة.
Mattermost هو منصة مراسلة فرق قابلة للاستضافة الذاتية؛ راجع الموقع الرسمي على
[mattermost.com](https://mattermost.com) لمعرفة تفاصيل المنتج والتنزيلات.
الحالة: Plugin مضمّن (رمز بوت + أحداث WebSocket). القنوات والمجموعات والرسائل المباشرة مدعومة.
Mattermost هي منصة مراسلة جماعية قابلة للاستضافة الذاتية؛ راجع الموقع الرسمي على
[mattermost.com](https://mattermost.com) للحصول على تفاصيل المنتج والتنزيلات.
## Plugin المضمّن
يأتي Mattermost كـ Plugin مضمّن في إصدارات OpenClaw الحالية، لذلك لا تحتاج
البُنى المجمّعة العادية إلى تثبيت منفصل.
البنيات المجمعة العادية إلى تثبيت منفصل.
إذا كنت تستخدم إصدارًا أقدم أو تثبيتًا مخصصًا لا يتضمن Mattermost،
إذا كنت تستخدم بنية أقدم أو تثبيتًا مخصصًا لا يتضمن Mattermost،
فثبّته يدويًا:
التثبيت عبر CLI (سجل npm):
@ -33,7 +33,7 @@ Mattermost هو منصة مراسلة فرق قابلة للاستضافة ال
openclaw plugins install @openclaw/mattermost
```
نسخة محلية من المستودع (عند التشغيل من مستودع git):
نسخة محلية (عند التشغيل من مستودع git):
```bash
openclaw plugins install ./path/to/local/mattermost-plugin
@ -41,13 +41,13 @@ openclaw plugins install ./path/to/local/mattermost-plugin
التفاصيل: [Plugins](/ar/tools/plugin)
## إعداد سريع
## الإعداد السريع
1. تأكد من أن Plugin Mattermost متاح.
- إصدارات OpenClaw المجمّعة الحالية تتضمنه بالفعل.
- يمكن لعمليات التثبيت الأقدم أو المخصصة إضافته يدويًا بالأوامر أعلاه.
2. أنشئ حساب bot في Mattermost وانسخ **bot token**.
3. انسخ **base URL** الخاص بـ Mattermost (مثل `https://chat.example.com`).
- إصدارات OpenClaw المجمعة الحالية تتضمنه بالفعل.
- يمكن للتثبيتات الأقدم/المخصصة إضافته يدويًا بالأوامر أعلاه.
2. أنشئ حساب بوت في Mattermost وانسخ **رمز البوت**.
3. انسخ **عنوان URL الأساسي** لـ Mattermost (مثل `https://chat.example.com`).
4. اضبط OpenClaw وابدأ Gateway.
الحد الأدنى من التكوين:
@ -65,10 +65,10 @@ openclaw plugins install ./path/to/local/mattermost-plugin
}
```
## أوامر slash الأصلية
## أوامر الشرطة المائلة الأصلية
أوامر slash الأصلية تعمل بنظام الاشتراك الاختياري. عند تفعيلها، يسجّل OpenClaw أوامر slash من نوع `oc_*` عبر
واجهة Mattermost API ويتلقى طلبات POST المرتدة على خادم HTTP الخاص بـ Gateway.
أوامر الشرطة المائلة الأصلية اختيارية التفعيل. عند تمكينها، يسجل OpenClaw أوامر الشرطة المائلة `oc_*` عبر
واجهة Mattermost API ويتلقى عمليات POST الراجعة على خادم HTTP الخاص بـ Gateway.
```json5
{
@ -78,7 +78,7 @@ openclaw plugins install ./path/to/local/mattermost-plugin
native: true,
nativeSkills: true,
callbackPath: "/api/channels/mattermost/command",
// استخدم هذا عندما لا يتمكن Mattermost من الوصول إلى Gateway مباشرة (reverse proxy/public URL).
// يُستخدم عندما يتعذر على Mattermost الوصول إلى Gateway مباشرةً (وكيل عكسي/عنوان URL عام).
callbackUrl: "https://gateway.example.com/api/channels/mattermost/command",
},
},
@ -88,50 +88,43 @@ openclaw plugins install ./path/to/local/mattermost-plugin
ملاحظات:
- القيمة الافتراضية لـ `native: "auto"` هي التعطيل في Mattermost. اضبط `native: true` للتفعيل.
- إذا لم يتم تحديد `callbackUrl`، فسيشتقه OpenClaw من host/port الخاص بـ Gateway مع `callbackPath`.
- `native: "auto"` يكون معطلاً افتراضيًا لـ Mattermost. اضبط `native: true` للتمكين.
- إذا تم حذف `callbackUrl`، فسيشتق OpenClaw قيمة منه من مضيف/منفذ Gateway مع `callbackPath`.
- في إعدادات الحسابات المتعددة، يمكن ضبط `commands` على المستوى الأعلى أو تحت
`channels.mattermost.accounts.<id>.commands` (قيم الحساب تتجاوز حقول المستوى الأعلى).
- يتم التحقق من نداءات الأوامر المرتدة باستخدام الرموز المميزة الخاصة بكل أمر التي يعيدها
Mattermost عندما يسجّل OpenClaw أوامر `oc_*`.
- تفشل نداءات slash المرتدة بشكل مغلق عند فشل التسجيل، أو كان الإقلاع جزئيًا، أو
لم يتطابق رمز النداء المرتد مع أحد الأوامر المسجّلة.
- متطلب قابلية الوصول: يجب أن يكون endpoint النداء المرتد قابلاً للوصول من خادم Mattermost.
- لا تضبط `callbackUrl` على `localhost` إلا إذا كان Mattermost يعمل على نفس المضيف/حيّز الشبكة مثل OpenClaw.
- لا تضبط `callbackUrl` على base URL الخاص بـ Mattermost ما لم يكن ذلك العنوان يمرر `/api/channels/mattermost/command` عبر reverse proxy إلى OpenClaw.
- فحص سريع هو `curl https://<gateway-host>/api/channels/mattermost/command`; يجب أن يعيد طلب GET القيمة `405 Method Not Allowed` من OpenClaw وليس `404`.
- متطلب قائمة السماح الصادرة في Mattermost:
- إذا كان callback الخاص بك يستهدف عناوين خاصة أو tailnet أو داخلية، فاضبط
`ServiceSettings.AllowedUntrustedInternalConnections` في Mattermost ليشمل host/domain الخاص بالـ callback.
- استخدم إدخالات host/domain، وليس عناوين URL كاملة.
- صحيح: `gateway.tailnet-name.ts.net`
- خطأ: `https://gateway.tailnet-name.ts.net`
- يتم التحقق من عمليات رد الأوامر باستخدام الرموز الخاصة بكل أمر التي يعيدها
Mattermost عندما يسجل OpenClaw أوامر `oc_*`.
- تفشل عمليات رد أوامر الشرطة المائلة بشكل مغلق عند فشل التسجيل، أو عند بدء تشغيل جزئي، أو
عندما لا يطابق رمز الرد أيًا من الأوامر المسجلة.
- متطلب قابلية الوصول: يجب أن يكون من الممكن الوصول إلى نقطة نهاية الرد من خادم Mattermost.
- لا تضبط `callbackUrl` على `localhost` إلا إذا كان Mattermost يعمل على نفس المضيف/مساحة اسم الشبكة مثل OpenClaw.
- لا تضبط `callbackUrl` على عنوان URL الأساسي لـ Mattermost ما لم يكن هذا العنوان يمرر `/api/channels/mattermost/command` عكسيًا إلى OpenClaw.
- فحص سريع هو `curl https://<gateway-host>/api/channels/mattermost/command`; يجب أن يعيد طلب GET القيمة `405 Method Not Allowed` من OpenClaw، وليس `404`.
- متطلب قائمة السماح لحركة الخروج في Mattermost:
- إذا كان الرد يستهدف عناوين خاصة/tailnet/داخلية، فاضبط
`ServiceSettings.AllowedUntrustedInternalConnections` في Mattermost ليشمل مضيف/نطاق الرد.
- استخدم إدخالات مضيف/نطاق، وليس عناوين URL كاملة.
- جيد: `gateway.tailnet-name.ts.net`
- سيئ: `https://gateway.tailnet-name.ts.net`
## متغيرات البيئة (الحساب الافتراضي)
اضبط هذه القيم على مضيف Gateway إذا كنت تفضّل استخدام متغيرات البيئة:
اضبط هذه القيم على مضيف Gateway إذا كنت تفضل استخدام متغيرات البيئة:
- `MATTERMOST_BOT_TOKEN=...`
- `MATTERMOST_URL=https://chat.example.com`
تنطبق متغيرات البيئة فقط على الحساب **الافتراضي** (`default`). أما الحسابات الأخرى فيجب أن تستخدم قيم التكوين.
تنطبق متغيرات البيئة فقط على الحساب **الافتراضي** (`default`). يجب أن تستخدم الحسابات الأخرى قيم التكوين.
<Note>
`MATTERMOST_URL` موجود في قائمة حظر كتل endpoint ولا يمكن ضبطه من
ملف workspace `.env`.
ويجب أن يأتي من بيئة shell أو من بيئة عملية Gateway حتى لا تتمكن
مساحات العمل غير الموثوقة من إعادة توجيه حركة Mattermost
إلى خادم مختلف. راجع
[ملفات workspace `.env`](/ar/gateway/security) للاطلاع على القائمة الكاملة.
</Note>
لا يمكن ضبط `MATTERMOST_URL` من ملف `.env` لمساحة العمل؛ راجع [ملفات `.env` لمساحة العمل](/ar/gateway/security).
## أوضاع الدردشة
يرد Mattermost على الرسائل الخاصة تلقائيًا. أما سلوك القنوات فيتحكم فيه `chatmode`:
يرد Mattermost على الرسائل المباشرة تلقائيًا. ويتم التحكم في سلوك القنوات بواسطة `chatmode`:
- `oncall` (الافتراضي): الرد فقط عند الإشارة إليه @mention في القنوات.
- `oncall` (افتراضي): الرد فقط عند الإشارة بـ @ في القنوات.
- `onmessage`: الرد على كل رسالة في القناة.
- `onchar`: الرد عندما تبدأ الرسالة ببادئة trigger.
- `onchar`: الرد عندما تبدأ الرسالة ببادئة تشغيل.
مثال على التكوين:
@ -148,19 +141,19 @@ openclaw plugins install ./path/to/local/mattermost-plugin
ملاحظات:
- لا يزال `onchar` يرد على إشارات @mention الصريحة.
- يتم احترام `channels.mattermost.requireMention` في التكوينات القديمة، لكن `chatmode` هو المفضل.
- يظل `onchar` يرد على إشارات @ الصريحة.
- تتم مراعاة `channels.mattermost.requireMention` للتكوينات القديمة، لكن `chatmode` هو المفضل.
## سلاسل الرسائل والجلسات
استخدم `channels.mattermost.replyToMode` للتحكم في ما إذا كانت الردود في القنوات والمجموعات تبقى في
القناة الرئيسية أو تبدأ سلسلة رسائل تحت المنشور الذي فعّلها.
استخدم `channels.mattermost.replyToMode` للتحكم فيما إذا كانت الردود في القنوات والمجموعات ستبقى في
القناة الرئيسية أو ستبدأ سلسلة رسائل تحت المنشور الذي تسبب في التشغيل.
- `off` (الافتراضي): الرد في سلسلة رسائل فقط عندما يكون المنشور الوارد ضمن سلسلة بالفعل.
- `first`: بالنسبة لمنشورات القنوات/المجموعات ذات المستوى الأعلى، ابدأ سلسلة رسائل تحت ذلك المنشور ووجّه
المحادثة إلى جلسة ضمن نطاق سلسلة الرسائل.
- `all`: السلوك نفسه مثل `first` في Mattermost حاليًا.
- تتجاهل الرسائل الخاصة هذا الإعداد وتبقى دون سلاسل رسائل.
- `off` (افتراضي): الرد في سلسلة رسائل فقط عندما يكون المنشور الوارد موجودًا بالفعل ضمن سلسلة.
- `first`: بالنسبة إلى منشورات القنوات/المجموعات ذات المستوى الأعلى، ابدأ سلسلة رسائل تحت ذلك المنشور ووجّه
المحادثة إلى جلسة مرتبطة بسلسلة الرسائل.
- `all`: نفس سلوك `first` في Mattermost حاليًا.
- تتجاهل الرسائل المباشرة هذا الإعداد وتبقى بدون سلاسل.
مثال على التكوين:
@ -176,27 +169,27 @@ openclaw plugins install ./path/to/local/mattermost-plugin
ملاحظات:
- تستخدم الجلسات ضمن نطاق سلسلة الرسائل معرّف المنشور الذي فعّلها كجذر للسلسلة.
- تستخدم الجلسات المرتبطة بسلسلة الرسائل معرّف المنشور الذي تسبب في التشغيل كجذر للسلسلة.
- `first` و`all` متكافئان حاليًا لأنه بمجرد أن يمتلك Mattermost جذر سلسلة رسائل،
تستمر المتابعات والوسائط في نفس تلك السلسلة.
فإن الأجزاء اللاحقة والوسائط تستمر في نفس السلسلة.
## التحكم في الوصول (الرسائل الخاصة)
## التحكم في الوصول (الرسائل المباشرة)
- الافتراضي: `channels.mattermost.dmPolicy = "pairing"` (المرسلون غير المعروفين يحصلون على رمز pairing).
- الافتراضي: `channels.mattermost.dmPolicy = "pairing"` (يرسل المرسلون غير المعروفين رمز اقتران).
- الموافقة عبر:
- `openclaw pairing list mattermost`
- `openclaw pairing approve mattermost <CODE>`
- الرسائل الخاصة العامة: `channels.mattermost.dmPolicy="open"` مع `channels.mattermost.allowFrom=["*"]`.
- الرسائل المباشرة العامة: `channels.mattermost.dmPolicy="open"` مع `channels.mattermost.allowFrom=["*"]`.
## القنوات (المجموعات)
- الافتراضي: `channels.mattermost.groupPolicy = "allowlist"` (مقيد بالإشارة mention).
- أضف المرسلين إلى قائمة السماح باستخدام `channels.mattermost.groupAllowFrom` (يوصى بمعرّفات المستخدمين).
- الافتراضي: `channels.mattermost.groupPolicy = "allowlist"` (محكومة بالإشارة).
- أضف المرسلين إلى قائمة السماح باستخدام `channels.mattermost.groupAllowFrom` (ويُوصى باستخدام معرّفات المستخدمين).
- توجد تجاوزات الإشارة لكل قناة تحت `channels.mattermost.groups.<channelId>.requireMention`
أو `channels.mattermost.groups["*"].requireMention` كقيمة افتراضية.
- المطابقة عبر `@username` قابلة للتغيّر ولا تُفعّل إلا عندما تكون `channels.mattermost.dangerouslyAllowNameMatching: true`.
- القنوات المفتوحة: `channels.mattermost.groupPolicy="open"` (مقيدة بالإشارة mention).
- ملاحظة وقت التشغيل: إذا كان `channels.mattermost` مفقودًا بالكامل، فسيعود وقت التشغيل إلى `groupPolicy="allowlist"` لفحوصات المجموعات (حتى لو كان `channels.defaults.groupPolicy` مضبوطًا).
- مطابقة `@username` قابلة للتغير ولا تُفعّل إلا عند ضبط `channels.mattermost.dangerouslyAllowNameMatching: true`.
- القنوات المفتوحة: `channels.mattermost.groupPolicy="open"` (محكومة بالإشارة).
- ملاحظة وقت التشغيل: إذا كان `channels.mattermost` مفقودًا بالكامل، فسيعود وقت التشغيل إلى `groupPolicy="allowlist"` لفحوصات المجموعات (حتى إذا كانت `channels.defaults.groupPolicy` مضبوطة).
مثال:
@ -216,27 +209,27 @@ openclaw plugins install ./path/to/local/mattermost-plugin
## الأهداف للتسليم الصادر
استخدم صيغ الأهداف هذه مع `openclaw message send` أو مع Cron/Webhooks:
استخدم تنسيقات الأهداف هذه مع `openclaw message send` أو Cron/Webhook:
- `channel:<id>` لقناة
- `user:<id>` لرسالة خاصة
- `@username` لرسالة خاصة (يتم حلّها عبر Mattermost API)
- `user:<id>` لرسالة مباشرة
- `@username` لرسالة مباشرة (يتم حلها عبر Mattermost API)
المعرّفات المبهمة المجردة (مثل `64ifufp...`) **ملتبسة** في Mattermost (معرّف مستخدم أم معرّف قناة).
المعرّفات المعتمة المجردة (مثل `64ifufp...`) **ملتبسة** في Mattermost (معرّف مستخدم أم معرّف قناة).
يقوم OpenClaw بحلّها **بأولوية المستخدم أولًا**:
يقوم OpenClaw بحلها **بأولوية المستخدم أولًا**:
- إذا كان المعرّف موجودًا كمستخدم (`GET /api/v4/users/<id>` ينجح)، يرسل OpenClaw **رسالة خاصة** عبر حلّ القناة المباشرة من خلال `/api/v4/channels/direct`.
- خلاف ذلك، يُعامل المعرّف على أنه **معرّف قناة**.
- إذا كان المعرّف موجودًا كمستخدم (`GET /api/v4/users/<id>` ينجح)، فإن OpenClaw يرسل **رسالة مباشرة** عبر حل القناة المباشرة باستخدام `/api/v4/channels/direct`.
- وإلا فسيتم التعامل مع المعرّف على أنه **معرّف قناة**.
إذا كنت تحتاج إلى سلوك حتمي، فاستخدم دائمًا البوادئ الصريحة (`user:<id>` / `channel:<id>`).
إذا كنت تحتاج إلى سلوك حتمي، فاستخدم دائمًا البادئات الصريحة (`user:<id>` / `channel:<id>`).
## إعادة محاولة قناة الرسائل الخاصة
## إعادة محاولة قناة الرسائل المباشرة
عندما يرسل OpenClaw إلى هدف رسالة خاصة في Mattermost ويحتاج أولًا إلى حل القناة المباشرة،
فإنه يعيد المحاولة تلقائيًا عند حالات الفشل العابرة في إنشاء القناة المباشرة.
عندما يرسل OpenClaw إلى هدف رسالة مباشرة في Mattermost ويحتاج أولًا إلى حل القناة المباشرة، فإنه
يعيد محاولة حالات الفشل العابرة في إنشاء القناة المباشرة افتراضيًا.
استخدم `channels.mattermost.dmChannelRetry` لضبط هذا السلوك على مستوى Plugin Mattermost بالكامل،
استخدم `channels.mattermost.dmChannelRetry` لضبط هذا السلوك عمومًا لـ Plugin Mattermost،
أو `channels.mattermost.accounts.<id>.dmChannelRetry` لحساب واحد.
```json5
@ -256,15 +249,15 @@ openclaw plugins install ./path/to/local/mattermost-plugin
ملاحظات:
- ينطبق هذا فقط على إنشاء قناة الرسائل الخاصة (`/api/v4/channels/direct`)، وليس على كل استدعاء لـ Mattermost API.
- تنطبق إعادة المحاولة على حالات الفشل العابرة مثل حدود المعدل، واستجابات 5xx، وأخطاء الشبكة أو انتهاء المهلة.
- تُعامل أخطاء العميل 4xx بخلاف `429` على أنها دائمة ولا يُعاد المحاولة فيها.
- ينطبق هذا فقط على إنشاء قناة الرسائل المباشرة (`/api/v4/channels/direct`)، وليس على كل استدعاء لـ Mattermost API.
- تنطبق إعادة المحاولة على الإخفاقات العابرة مثل حدود المعدل، واستجابات 5xx، وأخطاء الشبكة أو انتهاء المهلة.
- تُعامل أخطاء العميل 4xx بخلاف `429` على أنها دائمة ولا يُعاد المحاولة لها.
## بث المعاينة
يبث Mattermost التفكير ونشاط الأدوات والنص الجزئي للرد في **منشور معاينة مسودة** واحد يُنهى في مكانه عندما يصبح إرسال الإجابة النهائية آمنًا. تُحدَّث المعاينة على نفس معرّف المنشور بدلًا من إغراق القناة برسائل لكل جزء. وتُلغي النهايات الخاصة بالوسائط/الأخطاء تعديلات المعاينة المعلقة وتستخدم التسليم العادي بدلًا من تفريغ منشور معاينة مؤقت.
يبث Mattermost التفكير ونشاط الأدوات ونص الرد الجزئي في **منشور معاينة مسودة** واحد يكتمل في مكانه عند أمان إرسال الإجابة النهائية. تتحدث المعاينة على نفس معرّف المنشور بدلًا من إغراق القناة برسائل لكل جزء. تؤدي النهايات الخاصة بالوسائط/الأخطاء إلى إلغاء تعديلات المعاينة المعلقة وتستخدم التسليم العادي بدلًا من تفريغ منشور معاينة مؤقت.
فعّل ذلك عبر `channels.mattermost.streaming`:
يمكن التمكين عبر `channels.mattermost.streaming`:
```json5
{
@ -278,20 +271,20 @@ openclaw plugins install ./path/to/local/mattermost-plugin
ملاحظات:
- `partial` هو الخيار المعتاد: منشور معاينة واحد يُحرَّر مع نمو الرد، ثم يُنهى بالإجابة الكاملة.
- `partial` هو الخيار المعتاد: منشور معاينة واحد يُعدَّل مع نمو الرد، ثم يُنهى بالإجابة الكاملة.
- يستخدم `block` أجزاء مسودة بنمط الإلحاق داخل منشور المعاينة.
- يعرض `progress` معاينة حالة أثناء التوليد وينشر الإجابة النهائية فقط عند الاكتمال.
- `off` يعطّل بث المعاينة.
- إذا تعذر إنهاء البث في مكانه (مثلًا إذا حُذف المنشور أثناء البث)، يعود OpenClaw إلى إرسال منشور نهائي جديد حتى لا تضيع الإجابة أبدًا.
- تُحجب الحمولة الخاصة بالتفكير فقط من منشورات القناة، بما في ذلك النص الذي يصل على شكل blockquote `> Reasoning:`. اضبط `/reasoning on` لرؤية التفكير في أسطح أخرى؛ أما المنشور النهائي في Mattermost فيحتفظ بالإجابة فقط.
- راجع [Streaming](/ar/concepts/streaming#preview-streaming-modes) لمصفوفة الربط الخاصة بالقنوات.
- يعرض `progress` معاينة حالة أثناء الإنشاء ولا ينشر الإجابة النهائية إلا عند الاكتمال.
- يعطّل `off` بث المعاينة.
- إذا تعذر إنهاء البث في مكانه (على سبيل المثال إذا حُذف المنشور أثناء البث)، فسيعود OpenClaw إلى إرسال منشور نهائي جديد حتى لا تضيع الإجابة أبدًا.
- تُخفى الحمولات التي تحتوي على التفكير فقط من منشورات القنوات، بما في ذلك النص الذي يصل على شكل blockquote من نوع `> Reasoning:`. اضبط `/reasoning on` لرؤية التفكير في واجهات أخرى؛ أما المنشور النهائي في Mattermost فيحتفظ بالإجابة فقط.
- راجع [Streaming](/ar/concepts/streaming#preview-streaming-modes) للاطلاع على مصفوفة ربط القنوات.
## التفاعلات (أداة message)
## التفاعلات (أداة الرسائل)
- استخدم `message action=react` مع `channel=mattermost`.
- `messageId` هو معرّف منشور Mattermost.
- يقبل `emoji` أسماء مثل `thumbsup` أو `:+1:` (النقطتان اختياريتان).
- اضبط `remove=true` (boolean) لإزالة تفاعل.
- تقبل `emoji` أسماء مثل `thumbsup` أو `:+1:` (النقطتان اختيارية).
- اضبط `remove=true` (قيمة منطقية) لإزالة تفاعل.
- يتم تمرير أحداث إضافة/إزالة التفاعلات كأحداث نظام إلى جلسة الوكيل الموجّهة.
أمثلة:
@ -303,12 +296,12 @@ message action=react channel=mattermost target=channel:<channelId> messageId=<po
التكوين:
- `channels.mattermost.actions.reactions`: تفعيل/تعطيل إجراءات التفاعل (الافتراضي true).
- `channels.mattermost.actions.reactions`: تمكين/تعطيل إجراءات التفاعلات (الافتراضي true).
- تجاوز لكل حساب: `channels.mattermost.accounts.<id>.actions.reactions`.
## الأزرار التفاعلية (أداة message)
## الأزرار التفاعلية (أداة الرسائل)
أرسل رسائل تحتوي على أزرار قابلة للنقر. عندما ينقر مستخدم زرًا، يتلقى الوكيل
أرسل رسائل تحتوي على أزرار قابلة للنقر. عندما ينقر المستخدم زرًا، يتلقى الوكيل
الاختيار ويمكنه الرد.
فعّل الأزرار بإضافة `inlineButtons` إلى إمكانات القناة:
@ -323,7 +316,7 @@ message action=react channel=mattermost target=channel:<channelId> messageId=<po
}
```
استخدم `message action=send` مع وسيطة `buttons`. الأزرار هي مصفوفة ثنائية الأبعاد (صفوف من الأزرار):
استخدم `message action=send` مع المعامل `buttons`. الأزرار عبارة عن مصفوفة ثنائية الأبعاد (صفوف من الأزرار):
```
message action=send channel=mattermost target=channel:<channelId> buttons=[[{"text":"Yes","callback_data":"yes"},{"text":"No","callback_data":"no"}]]
@ -332,43 +325,43 @@ message action=send channel=mattermost target=channel:<channelId> buttons=[[{"te
حقول الزر:
- `text` (مطلوب): تسمية العرض.
- `callback_data` (مطلوب): القيمة التي تُرسل عند النقر (تُستخدم كمعرّف الإجراء).
- `callback_data` (مطلوب): القيمة التي تُعاد عند النقر (تُستخدم كمعرّف للإجراء).
- `style` (اختياري): `"default"` أو `"primary"` أو `"danger"`.
عندما ينقر مستخدم زرًا:
عندما ينقر المستخدم زرًا:
1. تُستبدل جميع الأزرار بسطر تأكيد (مثل: "✓ **Yes** selected by @user").
1. تُستبدل جميع الأزرار بسطر تأكيد (مثل: "✓ **تم اختيار نعم** بواسطة @user").
2. يتلقى الوكيل الاختيار كرسالة واردة ويرد.
ملاحظات:
- تستخدم نداءات الأزرار المرتدة تحقق HMAC-SHA256 (تلقائي، ولا حاجة إلى أي تكوين).
- يزيل Mattermost بيانات callback من استجابات API الخاصة به (ميزة أمان)، لذلك
تُزال جميع الأزرار عند النقر — ولا يمكن الإزالة الجزئية.
- تستخدم عمليات رد الأزرار التحقق باستخدام HMAC-SHA256 (تلقائيًا، ولا حاجة إلى تكوين).
- يزيل Mattermost بيانات الرد من استجابات API الخاصة به (ميزة أمان)، لذلك
تتم إزالة جميع الأزرار عند النقر — ولا يمكن الإزالة الجزئية.
- تُنقّى معرّفات الإجراءات التي تحتوي على شرطات أو شرطات سفلية تلقائيًا
(بسبب قيود التوجيه في Mattermost).
(قيد في توجيه Mattermost).
التكوين:
- `channels.mattermost.capabilities`: مصفوفة من سلاسل الإمكانات. أضف `"inlineButtons"` إلى
تفعيل وصف أداة الأزرار في system prompt الخاص بالوكيل.
- `channels.mattermost.interactions.callbackBaseUrl`: base URL خارجي اختياري لنداءات الأزرار
المرتدة (مثل `https://gateway.example.com`). استخدم هذا عندما لا يتمكن Mattermost من
الوصول إلى Gateway مباشرة عبر bind host الخاص به.
تمكين وصف أداة الأزرار في مطالبة النظام الخاصة بالوكيل.
- `channels.mattermost.interactions.callbackBaseUrl`: عنوان URL أساسي خارجي اختياري لعمليات رد
الأزرار (على سبيل المثال `https://gateway.example.com`). استخدم هذا عندما يتعذر على Mattermost
الوصول إلى Gateway عند مضيف الربط الخاص به مباشرةً.
- في إعدادات الحسابات المتعددة، يمكنك أيضًا ضبط الحقل نفسه تحت
`channels.mattermost.accounts.<id>.interactions.callbackBaseUrl`.
- إذا لم يتم تحديد `interactions.callbackBaseUrl`، فسيشتق OpenClaw عنوان callback URL من
- إذا تم حذف `interactions.callbackBaseUrl`، فسيشتق OpenClaw عنوان URL للرد من
`gateway.customBindHost` + `gateway.port`، ثم يعود إلى `http://localhost:<port>`.
- قاعدة قابلية الوصول: يجب أن يكون عنوان callback URL الخاص بالأزرار قابلاً للوصول من خادم Mattermost.
لا يعمل `localhost` إلا عندما يعمل Mattermost وOpenClaw على نفس المضيف/حيّز الشبكة.
- إذا كان هدف callback الخاص بك خاصًا أو على tailnet أو داخليًا، فأضف مضيفه/نطاقه إلى
- قاعدة قابلية الوصول: يجب أن يكون عنوان URL لرد الزر قابلاً للوصول من خادم Mattermost.
لا يعمل `localhost` إلا عندما يعمل Mattermost وOpenClaw على نفس المضيف/مساحة اسم الشبكة.
- إذا كان هدف الرد خاصًا/tailnet/داخليًا، فأضف مضيفه/نطاقه إلى
`ServiceSettings.AllowedUntrustedInternalConnections` في Mattermost.
### تكامل API مباشر (سكربتات خارجية)
### التكامل المباشر مع API (البرامج النصية الخارجية)
يمكن للسكربتات الخارجية وWebhooks نشر الأزرار مباشرة عبر Mattermost REST API
يمكن للبرامج النصية الخارجية وWebhook نشر الأزرار مباشرةً عبر Mattermost REST API
بدلًا من المرور عبر أداة `message` الخاصة بالوكيل. استخدم `buildButtonAttachments()` من
الـ Plugin متى أمكن؛ وإذا كنت سترسل JSON خامًا، فاتبع هذه القواعد:
Plugin متى أمكن؛ وإذا كنت سترسل JSON خامًا، فاتبع هذه القواعد:
**بنية الحمولة:**
@ -381,17 +374,17 @@ message action=send channel=mattermost target=channel:<channelId> buttons=[[{"te
{
actions: [
{
id: "mybutton01", // أحرف وأرقام فقط — انظر أدناه
type: "button", // مطلوب، وإلا سيتم تجاهل النقرات بصمت
name: "Approve", // تسمية العرض
style: "primary", // اختياري: "default" أو "primary" أو "danger"
id: "mybutton01", // alphanumeric only — see below
type: "button", // required, or clicks are silently ignored
name: "Approve", // display label
style: "primary", // optional: "default", "primary", "danger"
integration: {
url: "https://gateway.example.com/mattermost/interactions/default",
context: {
action_id: "mybutton01", // يجب أن يطابق معرّف الزر (لاستخدامه في lookup الاسم)
action_id: "mybutton01", // must match button id (for name lookup)
action: "approve",
// ... أي حقول مخصصة أخرى ...
_token: "<hmac>", // انظر قسم HMAC أدناه
// ... any custom fields ...
_token: "<hmac>", // see HMAC section below
},
},
},
@ -404,27 +397,27 @@ message action=send channel=mattermost target=channel:<channelId> buttons=[[{"te
**القواعد الحرجة:**
1. توضع attachments في `props.attachments`، وليس في `attachments` على المستوى الأعلى (وإلا يتم تجاهلها بصمت).
2. يحتاج كل إجراء إلى `type: "button"` — ومن دونه، تُبتلع النقرات بصمت.
3. يحتاج كل إجراء إلى حقل `id` — يتجاهل Mattermost الإجراءات التي لا تحتوي على IDs.
4. يجب أن يكون `id` الخاص بالإجراء **أبجديًا رقميًا فقط** (`[a-zA-Z0-9]`). فالشرطات والشرطات السفلية تعطل
توجيه الإجراءات على جانب خادم Mattermost (ويعيد 404). أزلها قبل الاستخدام.
1. يجب أن توضع المرفقات في `props.attachments`، وليس في `attachments` على المستوى الأعلى (وإلا يتم تجاهلها بصمت).
2. يحتاج كل إجراء إلى `type: "button"` — وبدونه، يتم ابتلاع النقرات بصمت.
3. يحتاج كل إجراء إلى حقل `id` — يتجاهل Mattermost الإجراءات التي لا تحتوي على معرّفات.
4. يجب أن يكون `id` الخاص بالإجراء **أبجديًا رقميًا فقط** (`[a-zA-Z0-9]`). الشرطات والشرطات السفلية تكسر
توجيه الإجراءات على جانب خادم Mattermost (تعيد 404). أزلها قبل الاستخدام.
5. يجب أن يطابق `context.action_id` قيمة `id` الخاصة بالزر حتى تعرض رسالة التأكيد
اسم الزر (مثل "Approve") بدلًا من معرّف خام.
6. `context.action_id` مطلوب — إذ يعيد معالج التفاعل 400 عند غيابه.
6. الحقل `context.action_id` مطلوب — يعيد معالج التفاعل 400 من دونه.
**توليد رمز HMAC:**
يتحقق Gateway من نقرات الأزرار باستخدام HMAC-SHA256. ويجب على السكربتات الخارجية توليد رموز
يتحقق Gateway من نقرات الأزرار باستخدام HMAC-SHA256. يجب على البرامج النصية الخارجية إنشاء رموز
تطابق منطق التحقق في Gateway:
1. اشتق secret من bot token:
1. اشتق السر من رمز البوت:
`HMAC-SHA256(key="openclaw-mattermost-interactions", data=botToken)`
2. أنشئ كائن context بجميع الحقول **باستثناء** `_token`.
3. نفّذ serialize باستخدام **مفاتيح مرتبة** و**من دون مسافات** (يستخدم Gateway الدالة `JSON.stringify`
2. ابنِ كائن السياق بكل الحقول **باستثناء** `_token`.
3. نفّذ التسلسل باستخدام **مفاتيح مرتبة** و**من دون مسافات** (يستخدم Gateway `JSON.stringify`
مع مفاتيح مرتبة، ما ينتج مخرجات مضغوطة).
4. وقّع باستخدام: `HMAC-SHA256(key=secret, data=serializedContext)`
5. أضف قيمة hex digest الناتجة كحقل `_token` داخل context.
4. وقّع: `HMAC-SHA256(key=secret, data=serializedContext)`
5. أضف ملخص hex الناتج كقيمة `_token` في السياق.
مثال Python:
@ -445,24 +438,24 @@ context = {**ctx, "_token": token}
المشكلات الشائعة في HMAC:
- تضيف `json.dumps` في Python مسافات افتراضيًا (`{"key": "val"}`). استخدم
- يضيف `json.dumps` في Python مسافات افتراضيًا (`{"key": "val"}`). استخدم
`separators=(",", ":")` لمطابقة المخرجات المضغوطة في JavaScript (`{"key":"val"}`).
- وقّع دائمًا **كل** حقول context (باستثناء `_token`). يزيل Gateway الحقل `_token` ثم
يوقّع كل ما تبقى. يؤدي توقيع مجموعة فرعية فقط إلى فشل صامت في التحقق.
- استخدم `sort_keys=True` — إذ يرتب Gateway المفاتيح قبل التوقيع، وقد يقوم Mattermost
بإعادة ترتيب حقول context عند تخزين الحمولة.
- اشتق secret من bot token (بشكل حتمي)، وليس من بايتات عشوائية. يجب أن يكون secret
- وقّع دائمًا **جميع** حقول السياق (باستثناء `_token`). يزيل Gateway الحقل `_token` ثم
يوقّع كل ما تبقى. توقيع مجموعة فرعية يسبب فشل التحقق بصمت.
- استخدم `sort_keys=True` — يرتب Gateway المفاتيح قبل التوقيع، وقد يعيد Mattermost
ترتيب حقول السياق عند تخزين الحمولة.
- اشتق السر من رمز البوت (بشكل حتمي)، وليس من بايتات عشوائية. يجب أن يكون السر
نفسه عبر العملية التي تنشئ الأزرار وGateway الذي يتحقق منها.
## محول الدليل
## مهايئ الدليل
يتضمن Plugin Mattermost محول دليل يحل أسماء القنوات والمستخدمين
عبر Mattermost API. وهذا يتيح استخدام الأهداف `#channel-name` و`@username` في
`openclaw message send` وتسليمات Cron/Webhooks.
يتضمن Plugin Mattermost مهايئ دليل يحل أسماء القنوات والمستخدمين
عبر Mattermost API. يتيح هذا استخدام الأهداف `#channel-name` و`@username` في
`openclaw message send` وعمليات تسليم Cron/Webhook.
لا حاجة إلى أي تكوين — يستخدم المحول bot token من تكوين الحساب.
لا حاجة إلى أي تكوين — يستخدم المهايئ رمز البوت من تكوين الحساب.
## حسابات متعددة
## الحسابات المتعددة
يدعم Mattermost حسابات متعددة تحت `channels.mattermost.accounts`:
@ -481,34 +474,34 @@ context = {**ctx, "_token": token}
## استكشاف الأخطاء وإصلاحها
- لا توجد ردود في القنوات: تأكد من وجود bot في القناة والإشارة إليه (oncall)، أو استخدم بادئة trigger (onchar)، أو اضبط `chatmode: "onmessage"`.
- أخطاء المصادقة: تحقق من bot token وbase URL وما إذا كان الحساب مفعّلًا.
- مشكلات الحسابات المتعددة: تنطبق متغيرات البيئة فقط على الحساب `default`.
- تعيد أوامر slash الأصلية `Unauthorized: invalid command token.`: لم يقبل OpenClaw
callback token. والأسباب المعتادة:
- فشل تسجيل أمر slash أو اكتمل جزئيًا فقط عند بدء التشغيل
- callback يصل إلى Gateway/حساب خاطئ
- لا يزال Mattermost يحتفظ بأوامر قديمة تشير إلى هدف callback سابق
- أُعيد تشغيل Gateway من دون إعادة تفعيل أوامر slash
- إذا توقفت أوامر slash الأصلية عن العمل، فتحقق من السجلات بحثًا عن
- لا توجد ردود في القنوات: تأكد من أن البوت موجود في القناة واذكره (oncall)، أو استخدم بادئة تشغيل (onchar)، أو اضبط `chatmode: "onmessage"`.
- أخطاء المصادقة: تحقق من رمز البوت وعنوان URL الأساسي وما إذا كان الحساب ممكّنًا.
- مشكلات الحسابات المتعددة: تنطبق متغيرات البيئة على الحساب `default` فقط.
- تعيد أوامر الشرطة المائلة الأصلية `Unauthorized: invalid command token.`: لم يقبل OpenClaw
رمز الرد. الأسباب الشائعة:
- فشل تسجيل أوامر الشرطة المائلة أو اكتمل جزئيًا فقط عند بدء التشغيل
- يصل الرد إلى Gateway/الحساب الخطأ
- لا يزال Mattermost يحتوي على أوامر قديمة تشير إلى هدف رد سابق
- أُعيد تشغيل Gateway من دون إعادة تفعيل أوامر الشرطة المائلة
- إذا توقفت أوامر الشرطة المائلة الأصلية عن العمل، فتحقق من السجلات بحثًا عن
`mattermost: failed to register slash commands` أو
`mattermost: native slash commands enabled but no commands could be registered`.
- إذا تم حذف `callbackUrl` وحذرت السجلات من أن callback حُلّ إلى
`http://127.0.0.1:18789/...`، فمن المحتمل أن يكون ذلك العنوان قابلاً للوصول فقط عندما
يعمل Mattermost على نفس المضيف/حيّز الشبكة مثل OpenClaw. اضبط
- إذا تم حذف `callbackUrl` وكانت السجلات تحذر من أن الرد تم حله إلى
`http://127.0.0.1:18789/...`، فمن المرجح أن يكون هذا العنوان قابلاً للوصول فقط عندما
يعمل Mattermost على نفس المضيف/مساحة اسم الشبكة مثل OpenClaw. اضبط
`commands.callbackUrl` صريحًا وقابلاً للوصول خارجيًا بدلًا من ذلك.
- تظهر الأزرار كمربعات بيضاء: قد يكون الوكيل يرسل بيانات أزرار غير صحيحة. تحقق من أن كل زر يحتوي على الحقلين `text` و`callback_data`.
- تُعرض الأزرار ولكن النقرات لا تفعل شيئًا: تحقق من أن `AllowedUntrustedInternalConnections` في تكوين خادم Mattermost يتضمن `127.0.0.1 localhost`، وأن `EnablePostActionIntegration` مضبوط على `true` في ServiceSettings.
- تعيد الأزرار 404 عند النقر: من المحتمل أن `id` الخاص بالزر يحتوي على شرطات أو شرطات سفلية. يتعطل موجه الإجراءات في Mattermost مع المعرفات غير الأبجدية الرقمية. استخدم `[a-zA-Z0-9]` فقط.
- يسجل Gateway `invalid _token`: عدم تطابق HMAC. تحقق من أنك توقّع جميع حقول context (وليس مجموعة فرعية)، وتستخدم مفاتيح مرتبة، وJSON مضغوطًا (من دون مسافات). راجع قسم HMAC أعلاه.
- يسجل Gateway `missing _token in context`: الحقل `_token` غير موجود في context الخاص بالزر. تأكد من تضمينه عند بناء حمولة integration.
- يعرض التأكيد معرّفًا خامًا بدلًا من اسم الزر: `context.action_id` لا يطابق `id` الخاص بالزر. اضبط كليهما على القيمة نفسها بعد التنقية.
- تظهر الأزرار كمربعات بيضاء: قد يكون الوكيل يرسل بيانات أزرار غير صحيحة البنية. تحقق من أن كل زر يحتوي على الحقلين `text` و`callback_data`.
- تُعرَض الأزرار لكن النقرات لا تفعل شيئًا: تحقق من أن `AllowedUntrustedInternalConnections` في تكوين خادم Mattermost يتضمن `127.0.0.1 localhost`، وأن `EnablePostActionIntegration` تساوي `true` في `ServiceSettings`.
- تعيد الأزرار 404 عند النقر: من المحتمل أن `id` الخاص بالزر يحتوي على شرطات أو شرطات سفلية. يتعطل موجّه الإجراءات في Mattermost مع المعرّفات غير الأبجدية الرقمية. استخدم `[a-zA-Z0-9]` فقط.
- يسجل Gateway الرسالة `invalid _token`: عدم تطابق HMAC. تحقق من أنك توقّع جميع حقول السياق (وليس مجموعة فرعية)، وتستخدم مفاتيح مرتبة، وJSON مضغوطًا (من دون مسافات). راجع قسم HMAC أعلاه.
- يسجل Gateway الرسالة `missing _token in context`: الحقل `_token` غير موجود في سياق الزر. تأكد من تضمينه عند بناء حمولة التكامل.
- يعرض التأكيد معرّفًا خامًا بدلًا من اسم الزر: `context.action_id` لا يطابق `id` الخاص بالزر. اضبط القيمتين على نفس القيمة المنقّاة.
- الوكيل لا يعرف الأزرار: أضف `capabilities: ["inlineButtons"]` إلى تكوين قناة Mattermost.
## ذو صلة
- [نظرة عامة على القنوات](/ar/channels) — جميع القنوات المدعومة
- [Pairing](/ar/channels/pairing) — مصادقة الرسائل الخاصة وتدفق pairing
- [المجموعات](/ar/channels/groups) — سلوك الدردشة الجماعية وتقييد الإشارة
- [الاقتران](/ar/channels/pairing) — مصادقة الرسائل المباشرة وتدفق الاقتران
- [المجموعات](/ar/channels/groups) — سلوك الدردشة الجماعية والتحكم عبر الإشارة
- [توجيه القنوات](/ar/channels/channel-routing) — توجيه الجلسات للرسائل
- [الأمان](/ar/gateway/security) — نموذج الوصول والتدعيم
- [الأمان](/ar/gateway/security) — نموذج الوصول والتقوية

100
docs/ar/channels/synology-chat.md
View File

@ -5,10 +5,10 @@ read_when:
summary: إعداد Webhook لـ Synology Chat وتكوين OpenClaw
title: Synology Chat
x-i18n:
generated_at: "2026-04-23T07:19:48Z"
generated_at: "2026-04-23T13:57:58Z"
model: gpt-5.4
provider: openai
source_hash: dda0d5d11e2526f4813b69ca914a63231003eb60d8bc2e1f030bcb3d77c8eda0
source_hash: a9cafbf543b8ce255e634bc4d54012652d3887ac23b31b97899dc7cec9d0688f
source_path: channels/synology-chat.md
workflow: 15
---
@ -16,18 +16,18 @@ x-i18n:
# Synology Chat
الحالة: Plugin مضمّن لقناة الرسائل المباشرة يستخدم Webhook الخاصة بـ Synology Chat.
يقبل Plugin الرسائل الواردة من Webhook الصادرة في Synology Chat ويرسل الردود
يقبل الـ Plugin الرسائل الواردة من Webhook الصادرة في Synology Chat ويرسل الردود
عبر Webhook واردة في Synology Chat.
## Plugin المضمّن
## Plugin مضمّن
يأتي Synology Chat كـ Plugin مضمّن في إصدارات OpenClaw الحالية، لذا فإن
البنيات المجمّعة العادية لا تحتاج إلى تثبيت منفصل.
يأتي Synology Chat كـ Plugin مضمّن في إصدارات OpenClaw الحالية، لذلك لا تحتاج
النسخ المعبأة العادية إلى تثبيت منفصل.
إذا كنت تستخدم بنية أقدم أو تثبيتًا مخصصًا يستبعد Synology Chat،
إذا كنت تستخدم إصدارًا أقدم أو تثبيتًا مخصصًا لا يتضمن Synology Chat،
فقم بتثبيته يدويًا:
التثبيت من نسخة محلية:
ثبّت من نسخة محلية:
```bash
openclaw plugins install ./path/to/local/synology-chat-plugin
@ -35,17 +35,17 @@ openclaw plugins install ./path/to/local/synology-chat-plugin
التفاصيل: [Plugins](/ar/tools/plugin)
## الإعداد السريع
## إعداد سريع
1. تأكد من أن Plugin الخاص بـ Synology Chat متاح.
- تتضمن إصدارات OpenClaw المجمّعة الحالية هذا Plugin بالفعل.
- يمكن للتثبيتات الأقدم/المخصصة إضافته يدويًا من نسخة المصدر باستخدام الأمر أعلاه.
- إصدارات OpenClaw المعبأة الحالية تتضمنه بالفعل.
- يمكن للإصدارات الأقدم أو التثبيتات المخصصة إضافته يدويًا من نسخة المصدر باستخدام الأمر أعلاه.
- يعرض `openclaw onboard` الآن Synology Chat في قائمة إعداد القنوات نفسها التي يستخدمها `openclaw channels add`.
- الإعداد غير التفاعلي: `openclaw channels add --channel synology-chat --token <token> --url <incoming-webhook-url>`
- إعداد غير تفاعلي: `openclaw channels add --channel synology-chat --token <token> --url <incoming-webhook-url>`
2. في تكاملات Synology Chat:
- أنشئ Webhook واردة وانسخ URL الخاص بها.
- أنشئ Webhook واردة وانسخ عنوان URL الخاص بها.
- أنشئ Webhook صادرة باستخدام الرمز السري الخاص بك.
3. وجّه URL الخاصة بـ Webhook الصادرة إلى Gateway الخاص بـ OpenClaw:
3. وجّه عنوان URL الخاص بـ Webhook الصادرة إلى Gateway الخاص بـ OpenClaw:
- `https://gateway-host/webhook/synology` افتراضيًا.
- أو `channels.synology-chat.webhookPath` المخصص لديك.
4. أكمل الإعداد في OpenClaw.
@ -56,15 +56,15 @@ openclaw plugins install ./path/to/local/synology-chat-plugin
تفاصيل مصادقة Webhook:
- يقبل OpenClaw رمز Webhook الصادرة من `body.token`، ثم
`?token=...`، ثم من الرؤوس.
- صيغ الرؤوس المقبولة:
`?token=...`، ثم الترويسات.
- صيغ الترويسات المقبولة:
- `x-synology-token`
- `x-webhook-token`
- `x-openclaw-token`
- `Authorization: Bearer <token>`
- تُرفض الرموز الفارغة أو المفقودة افتراضيًا.
- تفشل الرموز الفارغة أو المفقودة بشكل مغلق.
التهيئة الدنيا:
الحد الأدنى من التكوين:
```json5
{
@ -85,7 +85,7 @@ openclaw plugins install ./path/to/local/synology-chat-plugin
## متغيرات البيئة
بالنسبة إلى الحساب الافتراضي، يمكنك استخدام متغيرات البيئة:
بالنسبة للحساب الافتراضي، يمكنك استخدام متغيرات البيئة:
- `SYNOLOGY_CHAT_TOKEN`
- `SYNOLOGY_CHAT_INCOMING_URL`
@ -94,24 +94,18 @@ openclaw plugins install ./path/to/local/synology-chat-plugin
- `SYNOLOGY_RATE_LIMIT`
- `OPENCLAW_BOT_NAME`
تتجاوز قيم التهيئة متغيرات البيئة.
تتجاوز قيم التكوين متغيرات البيئة.
<Note>
يوجد `SYNOLOGY_CHAT_INCOMING_URL` ضمن قائمة حظر كتل نقاط النهاية ولا يمكن ضبطه
من ملف `.env` خاص بمساحة العمل. يجب أن يأتي من بيئة shell أو من
بيئة عملية Gateway حتى لا تتمكن مساحات العمل غير الموثوقة من إعادة توجيه
حركة مرور Synology Chat إلى Webhook مختلفة. راجع
[ملفات `.env` لمساحة العمل](/ar/gateway/security) للاطلاع على القائمة الكاملة.
</Note>
لا يمكن تعيين `SYNOLOGY_CHAT_INCOMING_URL` من ملف `.env` الخاص بمساحة العمل؛ راجع [ملفات `.env` الخاصة بمساحة العمل](/ar/gateway/security).
## سياسة الرسائل المباشرة والتحكم في الوصول
- `dmPolicy: "allowlist"` هو الإعداد الافتراضي الموصى به.
- يقبل `allowedUserIds` قائمة (أو سلسلة مفصولة بفواصل) من معرّفات مستخدمي Synology.
- في وضع `allowlist`، تُعامل قائمة `allowedUserIds` الفارغة على أنها سوء تهيئة ولن يبدأ مسار Webhook (استخدم `dmPolicy: "open"` للسماح للجميع).
- يتيح `dmPolicy: "open"` لأي مرسل.
- يتيح `dmPolicy: "open"` أي مرسل.
- يحظر `dmPolicy: "disabled"` الرسائل المباشرة.
- يبقى ربط مستلم الرد معتمدًا افتراضيًا على `user_id` الرقمي الثابت. يمثل `channels.synology-chat.dangerouslyAllowNameMatching: true` وضع توافق للطوارئ يعيد تفعيل البحث باستخدام اسم المستخدم/الاسم المستعار القابل للتغيير لتسليم الردود.
- يبقى ربط مستلم الرد معتمدًا على `user_id` الرقمي الثابت افتراضيًا. يشكل `channels.synology-chat.dangerouslyAllowNameMatching: true` وضع توافق طارئ يعيد تفعيل البحث باستخدام اسم المستخدم/الاسم المستعار القابل للتغيير لتسليم الردود.
- تعمل موافقات الاقتران مع:
- `openclaw pairing list synology-chat`
- `openclaw pairing approve synology-chat <CODE>`
@ -127,20 +121,20 @@ openclaw message send --channel synology-chat --target 123456 --text "Hello from
openclaw message send --channel synology-chat --target synology-chat:123456 --text "Hello again"
```
يتم دعم إرسال الوسائط عبر تسليم الملفات المستند إلى URL.
يجب أن تستخدم URL الملفات الصادرة `http` أو `https`، وتُرفض أهداف الشبكات الخاصة أو المحظورة بأي شكل آخر قبل أن يمرر OpenClaw URL إلى Webhook الخاصة بـ NAS.
عمليات إرسال الوسائط مدعومة عبر تسليم الملفات المعتمد على URL.
يجب أن تستخدم عناوين URL للملفات الصادرة `http` أو `https`، ويتم رفض أهداف الشبكة الخاصة أو المحجوبة بطريقة أخرى قبل أن يقوم OpenClaw بتمرير عنوان URL إلى Webhook الخاصة بـ NAS.
## الحسابات المتعددة
## حسابات متعددة
تُدعَم حسابات Synology Chat المتعددة ضمن `channels.synology-chat.accounts`.
يمكن لكل حساب تجاوز الرمز، وURL الواردة، ومسار Webhook، وسياسة الرسائل المباشرة، والحدود.
تُعزل جلسات الرسائل المباشرة لكل حساب ولكل مستخدم، لذا فإن `user_id` الرقمي نفسه
على حسابي Synology مختلفين لا يشارك حالة النص نفسه.
تتوفر عدة حسابات Synology Chat ضمن `channels.synology-chat.accounts`.
يمكن لكل حساب تجاوز الرمز وعنوان URL الوارد ومسار Webhook وسياسة الرسائل المباشرة والحدود.
تكون جلسات الرسائل المباشرة معزولة لكل حساب ولكل مستخدم، لذلك فإن `user_id` الرقمي نفسه
على حسابي Synology مختلفين لا يشارك حالة السجل.
امنح كل حساب مفعّل `webhookPath` مميزًا. يرفض OpenClaw الآن المسارات المتطابقة تمامًا
ويرفض بدء الحسابات المسماة التي ترث فقط مسار Webhook مشتركًا في إعدادات الحسابات المتعددة.
إذا كنت تحتاج عمدًا إلى هذا الإرث القديم لحساب مسمى، فاضبط
`dangerouslyAllowInheritedWebhookPath: true` على ذلك الحساب أو على `channels.synology-chat`,
لكن ستظل المسارات المتطابقة تمامًا مرفوضة افتراضيًا. ويفضَّل تعيين مسارات صريحة لكل حساب.
إذا كنت تحتاج عمدًا إلى الوراثة القديمة لحساب مسمّى، فعيّن
`dangerouslyAllowInheritedWebhookPath: true` على ذلك الحساب أو في `channels.synology-chat`,
ولكن لا تزال المسارات المتطابقة تمامًا تُرفض بشكل مغلق. يُفضل استخدام مسارات صريحة لكل حساب.
```json5
{
@ -169,33 +163,33 @@ openclaw message send --channel synology-chat --target synology-chat:123456 --te
- حافظ على سرية `token` وقم بتدويره إذا تسرّب.
- أبقِ `allowInsecureSsl: false` ما لم تكن تثق صراحةً بشهادة NAS محلية موقعة ذاتيًا.
- يتم التحقق من طلبات Webhook الواردة باستخدام الرمز وتُطبَّق عليها حدود المعدّل لكل مرسل.
- تستخدم عمليات التحقق من الرموز غير الصالحة مقارنة أسرار بزمن ثابت وتفشل افتراضيًا.
- فضّل `dmPolicy: "allowlist"` في بيئات الإنتاج.
- أبقِ `dangerouslyAllowNameMatching` معطّلًا ما لم تكن تحتاج صراحةً إلى تسليم الردود القديم المعتمد على اسم المستخدم.
- أبقِ `dangerouslyAllowInheritedWebhookPath` معطّلًا ما لم تكن تقبل صراحةً مخاطر التوجيه عبر المسار المشترك في إعدادات الحسابات المتعددة.
- يتم التحقق من طلبات Webhook الواردة بواسطة الرمز وتُطبق عليها حدود المعدل لكل مرسل.
- تستخدم عمليات التحقق من الرموز غير الصالحة مقارنة أسرار بزمن ثابت وتفشل بشكل مغلق.
- يُفضل `dmPolicy: "allowlist"` في بيئات الإنتاج.
- أبقِ `dangerouslyAllowNameMatching` معطلاً ما لم تكن تحتاج صراحةً إلى تسليم الردود القديم المعتمد على اسم المستخدم.
- أبقِ `dangerouslyAllowInheritedWebhookPath` معطلاً ما لم تكن تقبل صراحةً مخاطر التوجيه عبر المسار المشترك في إعداد حسابات متعددة.
## استكشاف الأخطاء وإصلاحها
- `Missing required fields (token, user_id, text)`:
- حمولة Webhook الصادرة تفتقد أحد الحقول المطلوبة
- إذا كان Synology يرسل الرمز في الرؤوس، فتأكد من أن Gateway/الوكيل العكسي يحافظ على تلك الرؤوس
- إذا كان Synology يرسل الرمز في الترويسات، فتأكد من أن الـ Gateway/الوكيل يحافظ على تلك الترويسات
- `Invalid token`:
- الرمز السري لـ Webhook الصادرة لا يطابق `channels.synology-chat.token`
- يصل الطلب إلى الحساب/مسار Webhook الخاطئ
- أزال وكيل عكسي رأس الرمز قبل وصول الطلب إلى OpenClaw
- السر الخاص بـ Webhook الصادرة لا يطابق `channels.synology-chat.token`
- الطلب يصل إلى الحساب أو مسار Webhook الخطأ
- أزال وكيل عكسي ترويسة الرمز قبل أن يصل الطلب إلى OpenClaw
- `Rate limit exceeded`:
- قد تؤدي محاولات الرموز غير الصالحة الكثيرة جدًا من المصدر نفسه إلى حظر ذلك المصدر مؤقتًا
- يخضع المرسلون الموثّقون أيضًا إلى حد منفصل لمعدل الرسائل لكل مستخدم
- قد تؤدي محاولات الرمز غير الصالح الكثيرة جدًا من المصدر نفسه إلى حظر ذلك المصدر مؤقتًا
- لدى المرسلين الموثقين أيضًا حد منفصل لمعدل الرسائل لكل مستخدم
- `Allowlist is empty. Configure allowedUserIds or use dmPolicy=open.`:
- تم تفعيل `dmPolicy="allowlist"` لكن لم يتم ضبط أي مستخدمين
- تم تفعيل `dmPolicy="allowlist"` لكن لم يتم تكوين أي مستخدمين
- `User not authorized`:
- لا يوجد `user_id` الرقمي للمرسل ضمن `allowedUserIds`
- `user_id` الرقمي الخاص بالمرسل غير موجود في `allowedUserIds`
## ذو صلة
- [نظرة عامة على القنوات](/ar/channels) — جميع القنوات المدعومة
- [الاقتران](/ar/channels/pairing) — مصادقة الرسائل المباشرة وتدفق الاقتران
- [المجموعات](/ar/channels/groups) — سلوك الدردشة الجماعية وبوابة الإشارات
- [المجموعات](/ar/channels/groups) — سلوك الدردشة الجماعية وضبط الإشارات
- [توجيه القنوات](/ar/channels/channel-routing) — توجيه الجلسات للرسائل
- [الأمان](/ar/gateway/security) — نموذج الوصول والتقوية

695
docs/ar/channels/telegram.md
View File

File diff suppressed because it is too large Load Diff

121
docs/ar/ci.md
View File

@ -1,107 +1,100 @@
---
read_when:
- تحتاج إلى فهم سبب تشغيل وظيفة CI أو عدم تشغيلها
- أنت تصحح أخطاء فحوصات GitHub Actions الفاشلة
summary: رسم وظيفة CI البياني، وبوابات النطاق، ومكافئات الأوامر المحلية
- أنت تقوم بتصحيح إخفاقات عمليات التحقق في GitHub Actions
summary: رسم وظائف CI البياني، وبوابات النطاق، ومكافئات الأوامر المحلية
title: مسار CI
x-i18n:
generated_at: "2026-04-23T07:20:46Z"
generated_at: "2026-04-23T13:58:01Z"
model: gpt-5.4
provider: openai
source_hash: 5c89c66204b203a39435cfc19de7b437867f2792bbfa2c3948371abde9f80e11
source_hash: c5a8ea0d8e428826169b0e6aced1caeb993106fe79904002125ace86b48cae1f
source_path: ci.md
workflow: 15
---
# مسار CI
يعمل CI عند كل push إلى `main` وعند كل pull request. ويستخدم تحديد نطاق ذكيًا لتخطي الوظائف المكلفة عندما تتغير مناطق غير مرتبطة فقط.
يعمل CI عند كل دفع إلى `main` وكل طلب سحب. ويستخدم تحديد نطاق ذكيًا لتخطي الوظائف المكلفة عندما تكون التغييرات محصورة في مناطق غير ذات صلة.
يملك QA Lab مسارات CI مخصصة خارج سير العمل الرئيسي ذي النطاق الذكي. يعمل
سير العمل `Parity gate` على تغييرات PR المطابقة وعبر التشغيل اليدوي؛ وهو
يبني بيئة تشغيل QA الخاصة ويقارن حزم الوكلاء التجريبية mock GPT-5.4 وOpus 4.6.
ويعمل سير العمل `QA-Lab - All Lanes` ليلًا على `main` وعبر
التشغيل اليدوي؛ حيث يوزّع mock parity gate ومسار Matrix الحي ومسار
Telegram الحي كوظائف متوازية. تستخدم الوظائف الحية بيئة `qa-live-shared`،
ويستخدم مسار Telegram عقود Convex. كما يشغّل `OpenClaw Release
Checks` مسارات QA Lab نفسها قبل الموافقة على الإصدار.
يمتلك QA Lab مسارات CI مخصصة خارج سير العمل الرئيسي ذي النطاق الذكي. يعمل سير عمل `Parity gate` على تغييرات PR المطابقة وعند التشغيل اليدوي؛ إذ يبني بيئة QA الخاصة ويقارن بين الحزم الوكيلة الوهمية GPT-5.4 وOpus 4.6. ويعمل سير عمل `QA-Lab - All Lanes` ليلًا على `main` وعند التشغيل اليدوي؛ إذ يوزع بوابة التماثل الوهمية، ومسار Matrix الحي، ومسار Telegram الحي كوظائف متوازية. تستخدم الوظائف الحية بيئة `qa-live-shared`، ويستخدم مسار Telegram عقود Convex. كما يشغّل `OpenClaw Release Checks` مسارات QA Lab نفسها قبل الموافقة على الإصدار.
## نظرة عامة على الوظائف
| الوظيفة | الغرض | متى تعمل |
| -------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------ |
| `preflight` | اكتشاف تغييرات الوثائق فقط، والنطاقات المتغيرة، والامتدادات المتغيرة، وبناء بيان CI | دائمًا في push وPR غير المسودات |
| `security-scm-fast` | اكتشاف المفاتيح الخاصة وتدقيق سير العمل عبر `zizmor` | دائمًا في push وPR غير المسودات |
| `security-dependency-audit` | تدقيق lockfile الإنتاجي من دون تبعيات مقابل تنبيهات npm | دائمًا في push وPR غير المسودات |
| `security-fast` | مجمّع مطلوب لوظائف الأمان السريعة | دائمًا في push وPR غير المسودات |
| `build-artifacts` | بناء `dist/` وواجهة Control UI وفحوصات العناصر المبنية والعناصر القابلة لإعادة الاستخدام لاحقًا | تغييرات مرتبطة بـ Node |
| `checks-fast-core` | مسارات صحة Linux السريعة مثل فحوصات bundled/plugin-contract/protocol | تغييرات مرتبطة بـ Node |
| `checks-fast-contracts-channels` | فحوصات عقود القنوات المجزأة مع نتيجة فحص مجمعة ثابتة | تغييرات مرتبطة بـ Node |
| `checks-node-extensions` | أجزاء اختبارات Plugin المضمّنة الكاملة عبر مجموعة الامتدادات | تغييرات مرتبطة بـ Node |
| `checks-node-core-test` | أجزاء اختبارات Node الأساسية، باستثناء القنوات، والمضمّنات، والعقود، ومسارات الامتدادات | تغييرات مرتبطة بـ Node |
| `extension-fast` | اختبارات مركزة لـ Plugins المضمّنة المتغيرة فقط | طلبات pull مع تغييرات الامتدادات |
| `check` | المكافئ المحلي الرئيسي المجزأ: أنواع الإنتاج، وlint، والحواجز، وأنواع الاختبار، وstrict smoke | تغييرات مرتبطة بـ Node |
| `check-additional` | حواجز البنية والحدود وأسطح الامتدادات وحدود الحزم وأجزاء gateway-watch | تغييرات مرتبطة بـ Node |
| `build-smoke` | اختبارات smoke لـ CLI المبني وsmoke لذاكرة بدء التشغيل | تغييرات مرتبطة بـ Node |
| `checks` | أداة تحقق لاختبارات القنوات على العناصر المبنية بالإضافة إلى توافق Node 22 في push فقط | تغييرات مرتبطة بـ Node |
| `check-docs` | فحوصات تنسيق الوثائق وlint والروابط المكسورة | عند تغيّر الوثائق |
| `skills-python` | Ruff + pytest للـ Skills المدعومة بـ Python | تغييرات مرتبطة بـ Python Skills |
| `checks-windows` | مسارات اختبارات خاصة بـ Windows | تغييرات مرتبطة بـ Windows |
| `macos-node` | مسار اختبارات TypeScript على macOS باستخدام العناصر المبنية المشتركة | تغييرات مرتبطة بـ macOS |
| `macos-swift` | lint وبناء واختبارات Swift لتطبيق macOS | تغييرات مرتبطة بـ macOS |
| `android` | اختبارات وحدات Android لكلا النكهتين بالإضافة إلى بناء واحد لـ debug APK | تغييرات مرتبطة بـ Android |
| الوظيفة | الغرض | وقت التشغيل |
| ------------------------------ | -------------------------------------------------------------------------------------------- | ----------------------------------- |
| `preflight` | اكتشاف تغييرات الوثائق فقط، والنطاقات المتغيرة، والإضافات المجمعة المتغيرة، وبناء بيان CI | دائمًا في عمليات الدفع وطلبات السحب غير المسودة |
| `security-scm-fast` | اكتشاف المفاتيح الخاصة وتدقيق سير العمل عبر `zizmor` | دائمًا في عمليات الدفع وطلبات السحب غير المسودة |
| `security-dependency-audit` | تدقيق ملف القفل الإنتاجي دون تبعيات مقابل تحذيرات npm | دائمًا في عمليات الدفع وطلبات السحب غير المسودة |
| `security-fast` | مجمّع مطلوب لوظائف الأمان السريعة | دائمًا في عمليات الدفع وطلبات السحب غير المسودة |
| `build-artifacts` | بناء `dist/` وواجهة Control UI وفحوصات نواتج البناء والنواتج القابلة لإعادة الاستخدام لاحقًا | تغييرات ذات صلة بـ Node |
| `checks-fast-core` | مسارات صحة سريعة على Linux مثل فحوصات المجمّع/عقد الإضافات/البروتوكول | تغييرات ذات صلة بـ Node |
| `checks-fast-contracts-channels` | فحوصات عقود القنوات المجزأة مع نتيجة فحص مجمعة مستقرة | تغييرات ذات صلة بـ Node |
| `checks-node-extensions` | أجزاء اختبار كاملة للإضافات المجمعة عبر مجموعة الإضافات | تغييرات ذات صلة بـ Node |
| `checks-node-core-test` | أجزاء اختبارات Node الأساسية، باستثناء مسارات القنوات والمجمّعات والعقود والإضافات | تغييرات ذات صلة بـ Node |
| `extension-fast` | اختبارات مركزة للإضافات المجمعة المتغيرة فقط | طلبات السحب التي تتضمن تغييرات في الإضافات |
| `check` | المكافئ الرئيسي المحلي المجزأ للبوابة: أنواع الإنتاج، وlint، والحواجز، وأنواع الاختبار، وsmoke صارم | تغييرات ذات صلة بـ Node |
| `check-additional` | حواجز البنية والحدود وسطح الإضافات وحدود الحزم وأجزاء مراقبة Gateway | تغييرات ذات صلة بـ Node |
| `build-smoke` | اختبارات smoke لـ CLI المبني وsmoke لذاكرة بدء التشغيل | تغييرات ذات صلة بـ Node |
| `checks` | أداة تحقق لاختبارات القنوات على النواتج المبنية بالإضافة إلى توافق Node 22 في عمليات الدفع فقط | تغييرات ذات صلة بـ Node |
| `check-docs` | تنسيق الوثائق وlint وفحوصات الروابط المعطلة | عند تغيير الوثائق |
| `skills-python` | Ruff + pytest للمهارات المعتمدة على Python | تغييرات ذات صلة بمهارات Python |
| `checks-windows` | مسارات اختبار خاصة بـ Windows | تغييرات ذات صلة بـ Windows |
| `macos-node` | مسار اختبارات TypeScript على macOS باستخدام نواتج البناء المشتركة | تغييرات ذات صلة بـ macOS |
| `macos-swift` | lint وبناء واختبارات Swift لتطبيق macOS | تغييرات ذات صلة بـ macOS |
| `android` | اختبارات وحدات Android لكلا النكهتين بالإضافة إلى بناء APK تصحيح واحد | تغييرات ذات صلة بـ Android |
## ترتيب الفشل السريع
## ترتيب الإخفاق السريع
تُرتَّب الوظائف بحيث تفشل الفحوصات الرخيصة قبل تشغيل الوظائف المكلفة:
1. يقرر `preflight` أي المسارات موجودة أصلًا. منطق `docs-scope` و`changed-scope` هو خطوات داخل هذه الوظيفة، وليس وظائف مستقلة.
2. تفشل `security-scm-fast` و`security-dependency-audit` و`security-fast` و`check` و`check-additional` و`check-docs` و`skills-python` بسرعة من دون انتظار الوظائف الأثقل الخاصة بالعناصر المبنية ومصفوفات المنصات.
1. يحدد `preflight` المسارات الموجودة أصلًا. ويكون منطق `docs-scope` و`changed-scope` خطوات داخل هذه الوظيفة، وليس وظائف مستقلة.
2. تفشل `security-scm-fast` و`security-dependency-audit` و`security-fast` و`check` و`check-additional` و`check-docs` و`skills-python` بسرعة دون انتظار وظائف النواتج والمصفوفات الخاصة بالمنصات الأثقل.
3. يتداخل `build-artifacts` مع مسارات Linux السريعة حتى يتمكن المستهلكون اللاحقون من البدء بمجرد جاهزية البناء المشترك.
4. بعد ذلك تتفرع مسارات المنصات وبيئات التشغيل الأثقل: `checks-fast-core` و`checks-fast-contracts-channels` و`checks-node-extensions` و`checks-node-core-test` و`extension-fast` الخاص بالـ PR فقط و`checks` و`checks-windows` و`macos-node` و`macos-swift` و`android`.
4. بعد ذلك تتفرع المسارات الأثقل الخاصة بالمنصات ووقت التشغيل: `checks-fast-core` و`checks-fast-contracts-channels` و`checks-node-extensions` و`checks-node-core-test` و`extension-fast` الخاصة بطلبات السحب فقط و`checks` و`checks-windows` و`macos-node` و`macos-swift` و`android`.
يوجد منطق النطاق في `scripts/ci-changed-scope.mjs` وتغطيه اختبارات وحدات في `src/scripts/ci-changed-scope.test.ts`.
تتحقق تعديلات سير عمل CI من رسم Node CI البياني بالإضافة إلى lint لسير العمل، لكنها لا تفرض بمفردها تشغيل بُنى Windows أو Android أو macOS الأصلية؛ إذ تبقى مسارات تلك المنصات محصورة في تغييرات مصدر المنصة.
تقتصر فحوصات Windows Node على أغلفة العمليات/المسارات الخاصة بـ Windows، ومساعدات تشغيل npm/pnpm/UI، وتكوين مدير الحزم، وأسطر سير عمل CI التي تشغّل ذلك المسار؛ أما تغييرات المصدر أو Plugin أو install-smoke أو الاختبارات غير المرتبطة فتبقى على مسارات Linux Node حتى لا تحجز عامل Windows ذي 16 vCPU لتغطية تُمارس بالفعل عبر أجزاء الاختبار العادية.
يعيد سير العمل المنفصل `install-smoke` استخدام سكربت النطاق نفسه عبر وظيفة `preflight` الخاصة به. فهو يحسب `run_install_smoke` من إشارة changed-smoke الأضيق، بحيث يعمل smoke الخاص بـ Docker/install لتغييرات التثبيت والتغليف والحاويات، وتغييرات إنتاج الامتدادات المضمّنة، والأسطح الأساسية لـ plugin/channel/gateway/Plugin SDK التي تمارسها وظائف Docker smoke. ولا تحجز التعديلات الخاصة بالاختبار فقط أو الوثائق فقط عمال Docker. ويجبر smoke الخاص بحزمة QR طبقة Docker `pnpm install` على إعادة التشغيل مع الحفاظ على ذاكرة BuildKit المؤقتة لمخزن pnpm، لذلك يظل يمارس التثبيت من دون إعادة تنزيل التبعيات في كل تشغيل. ويعيد gateway-network e2e استخدام صورة التشغيل المبنية سابقًا في الوظيفة، فيضيف تغطية WebSocket حقيقية من حاوية إلى حاوية من دون إضافة بناء Docker آخر. يقوم `test:docker:all` المحلي ببناء صورة تطبيق مشتركة واحدة من `scripts/e2e/Dockerfile` مسبقًا ويعيد استخدامها عبر مشغلات smoke لحاويات E2E؛ ويعكس سير العمل القابل لإعادة الاستخدام live/E2E هذا النمط عبر بناء ودفع صورة Docker E2E واحدة موسومة بـ SHA إلى GHCR قبل مصفوفة Docker، ثم تشغيل المصفوفة مع `OPENCLAW_SKIP_DOCKER_BUILD=1`. وتحتفظ اختبارات QR وinstaller في Docker بملفات Dockerfile الخاصة بها والمركزة على التثبيت. وتشغّل وظيفة منفصلة `docker-e2e-fast` ملف تعريف Docker المحدود للـ Plugin المضمّن تحت مهلة أمر مقدارها 120 ثانية: إصلاح تبعيات setup-entry بالإضافة إلى عزل فشل bundled-loader الاصطناعي. وتبقى مصفوفة التحديث/القنوات الكاملة للمضمّنات يدوية/للمجموعة الكاملة لأنها تنفذ عمليات تحديث npm حقيقية متكررة وتمريرات إصلاح doctor.
تتحقق تعديلات سير عمل CI من رسم Node CI البياني بالإضافة إلى lint لسير العمل، لكنها لا تفرض بمفردها عمليات بناء أصلية لـ Windows أو Android أو macOS؛ إذ تبقى مسارات تلك المنصات محصورة في تغييرات مصادر المنصة.
تُحصر فحوصات Windows Node في أغلفة العمليات/المسارات الخاصة بـ Windows، ومساعدات تشغيل npm/pnpm/UI، وإعدادات مدير الحزم، وأس surfaces سير عمل CI التي تشغّل ذلك المسار؛ أما تغييرات المصدر أو Plugin أو install-smoke أو الاختبارات غير المرتبطة فتظل على مسارات Linux Node حتى لا تحجز عامل Windows ذي 16 vCPU لتغطية يجري تنفيذها أصلًا بواسطة أجزاء الاختبار العادية.
يعيد سير العمل المنفصل `install-smoke` استخدام نص النطاق نفسه عبر وظيفة `preflight` الخاصة به. فهو يحسب `run_install_smoke` من إشارة smoke المتغيرة الأضيق، بحيث يعمل Docker/install smoke عند تغييرات التثبيت أو التغليف أو ما يتعلق بالحاويات أو تغييرات إنتاج الإضافات المجمعة أو أسطح Plugin/channel/Gateway/Plugin SDK الأساسية التي تمارسها وظائف Docker smoke. أما التعديلات الخاصة بالاختبارات فقط أو الوثائق فقط فلا تحجز عمال Docker. ويفرض smoke حزمة QR إعادة تشغيل طبقة Docker `pnpm install` مع الحفاظ على ذاكرة التخزين المؤقت BuildKit pnpm store، لذا يظل يختبر التثبيت دون إعادة تنزيل التبعيات في كل تشغيل. ويعيد e2e لشبكة gateway استخدام صورة وقت التشغيل المبنية سابقًا في الوظيفة، لذا يضيف تغطية WebSocket حقيقية من حاوية إلى حاوية دون إضافة بناء Docker آخر. يقوم `test:docker:all` المحلي ببناء صورة اختبار حي مشتركة واحدة وصورة تطبيق مبني مشتركة واحدة من `scripts/e2e/Dockerfile`، ثم يشغّل مسارات smoke الحية/E2E بالتوازي مع `OPENCLAW_SKIP_DOCKER_BUILD=1`؛ ويمكن ضبط التوازي الافتراضي البالغ 4 باستخدام `OPENCLAW_DOCKER_ALL_PARALLELISM`. ويوقف المجمّع المحلي جدولة مسارات جديدة مجمعة بعد أول إخفاق افتراضيًا، ولكل مسار مهلة 120 دقيقة يمكن تجاوزها باستخدام `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`. وتعمل المسارات الحساسة لبدء التشغيل أو المزود بشكل حصري بعد المجموعة المتوازية. ويعكس سير العمل الحي/E2E القابل لإعادة الاستخدام نمط الصورة المشتركة ببناء ودفع صورة Docker E2E واحدة مميزة بـ SHA إلى GHCR قبل مصفوفة Docker، ثم تشغيل المصفوفة مع `OPENCLAW_SKIP_DOCKER_BUILD=1`. ويشغّل سير العمل الحي/E2E المجدول مجموعة Docker الكاملة لمسار الإصدار يوميًا. وتحافظ اختبارات Docker الخاصة بـ QR والمثبت على Dockerfiles الخاصة بها والمركزة على التثبيت. وتعمل وظيفة منفصلة `docker-e2e-fast` على ملف تعريف Docker المحدود للإضافات المجمعة ضمن مهلة أوامر قدرها 120 ثانية: إصلاح تبعيات setup-entry بالإضافة إلى عزل الإخفاق الاصطناعي لمحمّل الإضافات المجمعة. أما المصفوفة الكاملة لتحديث الإضافات/القنوات المجمعة فتبقى يدوية/للمجموعة الكاملة لأنها تنفذ عمليات npm update حقيقية متكررة وتمريرات doctor repair.
يوجد منطق المسارات المتغيرة المحلي في `scripts/changed-lanes.mjs` ويُنفذ بواسطة `scripts/check-changed.mjs`. وهذه البوابة المحلية أكثر صرامة بشأن حدود البنية من نطاق منصة CI الواسع: فالتغييرات الأساسية في الإنتاج تشغّل typecheck للإنتاج الأساسي بالإضافة إلى اختبارات الأساس، وتغييرات اختبارات الأساس فقط تشغّل فقط typecheck/اختبارات اختبارات الأساس، وتغييرات إنتاج الامتدادات تشغّل typecheck لإنتاج الامتدادات بالإضافة إلى اختبارات الامتدادات، وتغييرات اختبارات الامتدادات فقط تشغّل فقط typecheck/اختبارات اختبارات الامتدادات. أما تغييرات Plugin SDK العامة أو plugin-contract فتوسّع التحقق ليشمل الامتدادات لأن الامتدادات تعتمد على تلك العقود الأساسية. وتشغّل زيادات الإصدار الخاصة ببيانات الإصدار الوصفية فقط فحوصات مستهدفة للإصدار/التكوين/التبعيات الجذرية. وتفشل التغييرات الجذرية/التهيئية غير المعروفة إلى جميع المسارات كخيار آمن.
يوجد منطق المسارات المحلية المتغيرة في `scripts/changed-lanes.mjs` ويُنفذ بواسطة `scripts/check-changed.mjs`. وهذه البوابة المحلية أكثر صرامة بشأن حدود البنية من نطاق منصة CI العام: تغييرات الإنتاج الأساسية تشغّل فحص أنواع الإنتاج الأساسي بالإضافة إلى الاختبارات الأساسية، وتغييرات الاختبارات الأساسية فقط تشغّل فقط فحص أنواع الاختبار الأساسي/الاختبارات، وتغييرات إنتاج الإضافات تشغّل فحص أنواع إنتاج الإضافات بالإضافة إلى اختبارات الإضافات، وتغييرات اختبارات الإضافات فقط تشغّل فقط فحص أنواع اختبارات الإضافات/الاختبارات. كما أن تغييرات Plugin SDK العامة أو plugin-contract توسّع التحقق ليشمل الإضافات لأن الإضافات تعتمد على تلك العقود الأساسية. وتشغّل زيادات الإصدار الخاصة ببيانات الإصدار فقط فحوصات مستهدفة للإصدار/الإعداد/تبعيات الجذر. أما تغييرات الجذر/الإعداد غير المعروفة فتفشل احتياطيًا إلى جميع المسارات.
في عمليات push، تضيف مصفوفة `checks` المسار `compat-node22` الخاص بعمليات push فقط. أما في pull requests، فيُتخطى هذا المسار وتبقى المصفوفة مركزة على مسارات الاختبار/القنوات العادية.
في عمليات الدفع، تضيف مصفوفة `checks` المسار الخاص بالدفع فقط `compat-node22`. وفي طلبات السحب، يُتخطى هذا المسار وتبقى المصفوفة مركزة على مسارات الاختبار/القنوات العادية.
تُقسَّم أو تُوازَن أبطأ عائلات اختبارات Node بحيث تبقى كل وظيفة صغيرة: فتعمد عقود القنوات إلى تقسيم تغطية registry وcore إلى ستة أجزاء موزونة إجمالًا، وتوازن اختبارات Plugins المضمّنة عبر ستة عمال امتدادات، ويعمل auto-reply على ثلاثة عمال موزونين بدلًا من ستة عمال صغار، وتُوزَّع إعدادات agentic gateway/plugin عبر وظائف agentic Node الحالية الخاصة بالمصدر فقط بدلًا من انتظار العناصر المبنية. وتستخدم اختبارات browser وQA والوسائط وPlugins المتنوعة الواسعة إعدادات Vitest المخصصة لها بدلًا من المجموعة العامة المشتركة للـ Plugins. ويستخدم مسار agents الواسع مجدول Vitest الموازي المشترك على مستوى الملفات لأنه يهيمن عليه الاستيراد/الجدولة بدلًا من ملف اختبار بطيء واحد. ويعمل `runtime-config` مع جزء infra core-runtime حتى لا يمتلك الجزء المشترك للتشغيل الذيل الأخير. ويُبقي `check-additional` أعمال compile/canary لحدود الحزم معًا ويفصل بنية topology في وقت التشغيل عن تغطية gateway watch؛ بينما يشغّل جزء boundary guard حواجزه الصغيرة المستقلة بالتوازي داخل وظيفة واحدة. وتعمل Gateway watch واختبارات القنوات وجزء حدود دعم core بالتوازي داخل `build-artifacts` بعد أن يكون `dist/` و`dist-runtime/` قد بُنيا بالفعل، مع الاحتفاظ بأسماء الفحوصات القديمة كوظائف تحقق خفيفة مع تجنب عاملين إضافيين من Blacksmith وطابور مستهلك ثانٍ للعناصر المبنية.
يشغّل Android CI كلًا من `testPlayDebugUnitTest` و`testThirdPartyDebugUnitTest`، ثم يبني Play debug APK. ولا تملك النكهة third-party مجموعة مصادر أو manifest منفصلًا؛ ومع ذلك فإن مسار اختبار الوحدات الخاص بها يترجم تلك النكهة مع إشارات BuildConfig الخاصة بـ SMS/call-log، مع تجنب وظيفة تغليف debug APK مكررة في كل push ذي صلة بـ Android.
يقتصر `extension-fast` على PR فقط لأن عمليات push تشغّل بالفعل أجزاء اختبارات Plugin المضمّنة الكاملة. وهذا يحافظ على ملاحظات سريعة للـ Plugins المتغيرة أثناء المراجعة من دون حجز عامل Blacksmith إضافي على `main` لتغطية موجودة بالفعل في `checks-node-extensions`.
تُقسَّم عائلات اختبارات Node الأبطأ أو تُوازَن بحيث تبقى كل وظيفة صغيرة: تقسم عقود القنوات تغطية السجل والتغطية الأساسية إلى ستة أجزاء موزونة إجمالًا، وتُوازَن اختبارات الإضافات المجمعة عبر ستة عمال إضافات، ويعمل auto-reply على ثلاثة عمال موزونين بدلًا من ستة عمال صغار، وتُوزع إعدادات agentic الخاصة بـ gateway/plugin عبر وظائف Node المصدرية agentic القائمة بدلًا من انتظار النواتج المبنية. وتستخدم اختبارات browser وQA والوسائط والإضافات المتنوعة الواسعة إعدادات Vitest المخصصة لها بدلًا من الجامع المشترك للإضافات. ويستخدم مسار agents الواسع مجدول التوازي على مستوى الملفات المشترك في Vitest لأنه يهيمن عليه الاستيراد/الجدولة بدلًا من أن يملكه ملف اختبار بطيء واحد. ويعمل `runtime-config` مع جزء infra core-runtime حتى لا يمتلك جزء وقت التشغيل المشترك الذيل. ويحافظ `check-additional` على أعمال الترجمة/الكناري الخاصة بحدود الحزم معًا ويفصل بنية طوبولوجيا وقت التشغيل عن تغطية مراقبة Gateway؛ ويشغّل جزء حراسة الحدود حواجزه الصغيرة المستقلة بالتوازي داخل وظيفة واحدة. وتعمل مراقبة Gateway واختبارات القنوات وجزء حدود الدعم الأساسي بالتوازي داخل `build-artifacts` بعد أن يكون `dist/` و`dist-runtime/` قد بُنيا بالفعل، مع الاحتفاظ بأسماء الفحوصات القديمة كوظائف تحقق خفيفة الوزن مع تجنب عاملين إضافيين من Blacksmith وطابور ثانٍ لمستهلكي النواتج.
يشغّل Android CI كلاً من `testPlayDebugUnitTest` و`testThirdPartyDebugUnitTest`، ثم يبني APK التصحيح الخاص بـ Play. ولا تمتلك النكهة الخارجية مجموعة مصادر أو manifest منفصلين؛ إلا أن مسار اختبار الوحدات الخاص بها لا يزال يترجم تلك النكهة باستخدام إشارات BuildConfig الخاصة بـ SMS/call-log، مع تجنب وظيفة تغليف APK تصحيح مكررة في كل دفع ذي صلة بـ Android.
يكون `extension-fast` خاصًا بطلبات السحب فقط لأن عمليات الدفع تشغّل بالفعل الأجزاء الكاملة لاختبارات الإضافات المجمعة. وهذا يحافظ على تغذية راجعة سريعة للإضافات المتغيرة أثناء المراجعة دون حجز عامل Blacksmith إضافي على `main` لتغطية موجودة أصلًا في `checks-node-extensions`.
قد يضع GitHub علامة `cancelled` على الوظائف المستبدلة عندما يصل push أحدث إلى نفس مرجع PR أو مرجع `main`. تعامل مع ذلك باعتباره ضجيج CI ما لم يكن أحدث تشغيل للمرجع نفسه فاشلًا أيضًا. تستخدم فحوصات الأجزاء المجمعة `!cancelled() && always()` حتى تبلّغ عن حالات فشل الأجزاء العادية، لكنها لا تُصف بعد أن يكون سير العمل كله قد استُبدل بالفعل.
يخضع مفتاح التزامن في CI للإصدار (`CI-v7-*`) حتى لا يتمكن zombie على جانب GitHub في مجموعة انتظار قديمة من حجب تشغيلات main الأحدث إلى أجل غير مسمى.
قد يعلّم GitHub الوظائف المستبدلة على أنها `cancelled` عندما يصل دفع أحدث إلى نفس مرجع PR أو مرجع `main`. تعامل مع ذلك على أنه ضجيج CI ما لم يكن أحدث تشغيل لنفس المرجع يفشل أيضًا. وتستخدم فحوصات الأجزاء المجمعة `!cancelled() && always()` حتى تستمر في الإبلاغ عن إخفاقات الأجزاء العادية، لكنها لا تُصفّ بعد أن يكون سير العمل كله قد استُبدل بالفعل.
ومفتاح التزامن في CI مُرقّم بالإصدار (`CI-v7-*`) حتى لا يتمكن عنصر GitHub عالق في مجموعة انتظار قديمة من حظر تشغيلات `main` الأحدث إلى أجل غير مسمى.
## المشغّلات
| المشغّل | الوظائف |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ubuntu-24.04` | `preflight`، ووظائف الأمان السريعة والمجمِّعات (`security-scm-fast` و`security-dependency-audit` و`security-fast`)، وفحوصات protocol/contract/bundled السريعة، وفحوصات عقود القنوات المجزأة، وأجزاء `check` باستثناء lint، وأجزاء ومجمِّعات `check-additional`، وأدوات التحقق المجمعة لاختبارات Node، وفحوصات الوثائق، وPython Skills، وworkflow-sanity، وlabeler، وauto-response؛ كما يستخدم preflight الخاص بـ install-smoke Ubuntu المستضاف من GitHub حتى تتمكن مصفوفة Blacksmith من الاصطفاف مبكرًا |
| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`، وbuild-smoke، وأجزاء اختبارات Linux Node، وأجزاء اختبارات Plugin المضمّنة، و`android` |
| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`، الذي لا يزال حساسًا بما يكفي للـ CPU بحيث كانت تكلفة 8 vCPU أعلى من الوفر الذي حققته؛ وبُنى Docker الخاصة بـ install-smoke، حيث كانت تكلفة وقت الانتظار لـ 32 vCPU أعلى من الوفر الذي حققته |
| `blacksmith-16vcpu-windows-2025` | `checks-windows` |
| `blacksmith-6vcpu-macos-latest` | `macos-node` على `openclaw/openclaw`؛ وتعود fork إلى `macos-latest` |
| `blacksmith-12vcpu-macos-latest` | `macos-swift` على `openclaw/openclaw`؛ وتعود fork إلى `macos-latest` |
| المشغّل | الوظائف |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ubuntu-24.04` | `preflight`، ووظائف الأمان السريعة ومجمّعاتها (`security-scm-fast` و`security-dependency-audit` و`security-fast`)، وفحوصات البروتوكول/العقود/المجمّعات السريعة، وفحوصات عقود القنوات المجزأة، وأجزاء `check` باستثناء lint، وأجزاء ومجمّعات `check-additional`، وأدوات التحقق المجمعة لاختبارات Node، وفحوصات الوثائق، وSkills الخاصة بـ Python، وworkflow-sanity، وlabeler، وauto-response؛ كما يستخدم preflight الخاص بـ install-smoke أيضًا Ubuntu المستضاف من GitHub حتى تتمكن مصفوفة Blacksmith من الاصطفاف مبكرًا |
| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`، وbuild-smoke، وأجزاء اختبارات Linux Node، وأجزاء اختبارات Plugin المجمّعة، و`android` |
| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`، الذي لا يزال حساسًا لاستهلاك CPU بدرجة تجعل 8 vCPU أكثر كلفة مما وفرته؛ وبناءات Docker الخاصة بـ install-smoke، حيث كانت كلفة وقت الانتظار لـ 32-vCPU أعلى مما وفرته |
| `blacksmith-16vcpu-windows-2025` | `checks-windows` |
| `blacksmith-6vcpu-macos-latest` | `macos-node` على `openclaw/openclaw`؛ وتعود التفرعات إلى `macos-latest` |
| `blacksmith-12vcpu-macos-latest` | `macos-swift` على `openclaw/openclaw`؛ وتعود التفرعات إلى `macos-latest` |
## المكافئات المحلية
```bash
pnpm changed:lanes # افحص مصنّف المسارات المتغيرة المحلي لـ origin/main...HEAD
pnpm check:changed # البوابة المحلية الذكية: typecheck/lint/tests المتغيرة حسب مسار الحدود
pnpm check # البوابة المحلية السريعة: tsgo للإنتاج + lint مجزأ + حواجز سريعة متوازية
pnpm changed:lanes # افحص مصنّف المسارات المحلية المتغيرة لـ origin/main...HEAD
pnpm check:changed # البوابة المحلية الذكية: typecheck/lint/tests المتغيرة بحسب مسار الحدود
pnpm check # البوابة المحلية السريعة: `tsgo` للإنتاج + lint مجزأ + حواجز سريعة متوازية
pnpm check:test-types
pnpm check:timed # البوابة نفسها مع توقيتات لكل مرحلة
pnpm build:strict-smoke
pnpm check:architecture
pnpm test:gateway:watch-regression
pnpm test # اختبارات vitest
pnpm test # اختبارات `vitest`
pnpm test:channels
pnpm test:contracts:channels
pnpm check:docs # تنسيق الوثائق + lint + الروابط المكسورة
pnpm build # ابنِ dist عندما تكون مسارات عناصر CI المبنية/build-smoke مهمة
node scripts/ci-run-timings.mjs <run-id> # لخّص زمن التنفيذ الفعلي، وزمن الانتظار، وأبطأ الوظائف
pnpm check:docs # تنسيق الوثائق + lint + الروابط المعطلة
pnpm build # ابنِ dist عندما تكون مسارات نواتج CI/‏build-smoke مهمة
node scripts/ci-run-timings.mjs <run-id> # لخّص وقت التنفيذ الكلي ووقت الانتظار وأبطأ الوظائف
```

268
docs/ar/cli/gateway.md
View File

@ -1,26 +1,26 @@
---
read_when:
- تشغيل Gateway من خلال CLI ‏(للتطوير أو الخوادم)
- تصحيح مصادقة Gateway، وأوضاع الربط، والاتصال
- اكتشاف Gateways عبر Bonjour ‏(DNS-SD المحلي + واسع النطاق)
summary: CLI الخاص بـ OpenClaw Gateway ‏(`openclaw gateway`) — تشغيل Gateways والاستعلام عنها واكتشافها
title: gateway
- تشغيل Gateway من CLI (للتطوير أو الخوادم)
- تصحيح أخطاء مصادقة Gateway وأوضاع الربط والاتصال
- اكتشاف Gateways عبر Bonjour ‏(المحلي + DNS-SD واسع النطاق)
summary: OpenClaw Gateway CLI (`openclaw gateway`) — تشغيل Gateways والاستعلام عنها واكتشافها
title: Gateway
x-i18n:
generated_at: "2026-04-23T07:22:18Z"
generated_at: "2026-04-23T13:58:02Z"
model: gpt-5.4
provider: openai
source_hash: 30d261a33e54bed10c17c14d09d0dd2b8e227bbf9f0ed415e332e7bda4803f1e
source_hash: f9160017a4d1326819f6b4d067bd99aa02ee37689b96c185defedef6200c19cf
source_path: cli/gateway.md
workflow: 15
---
# CLI الخاص بـ Gateway
# Gateway CLI
Gateway هو خادم WebSocket الخاص بـ OpenClaw ‏(القنوات، والعُقد، والجلسات، وHooks).
يُعد Gateway خادم WebSocket الخاص بـ OpenClaw ‏(القنوات، والعُقد، والجلسات، والخطافات).
توجد الأوامر الفرعية في هذه الصفحة تحت `openclaw gateway …`.
توجد الأوامر الفرعية في هذه الصفحة ضمن `openclaw gateway …`.
مستندات ذات صلة:
المستندات ذات الصلة:
- [/gateway/bonjour](/ar/gateway/bonjour)
- [/gateway/discovery](/ar/gateway/discovery)
@ -34,7 +34,7 @@ Gateway هو خادم WebSocket الخاص بـ OpenClaw ‏(القنوات، و
openclaw gateway
```
الاسم البديل للمقدمة الأمامية:
الاسم البديل للتشغيل في الواجهة الأمامية:
```bash
openclaw gateway run
@ -42,59 +42,59 @@ openclaw gateway run
ملاحظات:
- افتراضيًا، يرفض Gateway البدء ما لم يتم ضبط `gateway.mode=local` في `~/.openclaw/openclaw.json`. استخدم `--allow-unconfigured` للتشغيلات المخصصة/التطويرية.
- من المتوقع أن يكتب `openclaw onboard --mode local` و`openclaw setup` القيمة `gateway.mode=local`. إذا كان الملف موجودًا لكن `gateway.mode` مفقودة، فاعتبر ذلك إعدادًا معطوبًا أو تم العبث به وقم بإصلاحه بدلًا من افتراض الوضع المحلي ضمنيًا.
- إذا كان الملف موجودًا وكانت `gateway.mode` مفقودة، فسيتعامل Gateway مع ذلك على أنه تلف مريب في الإعدادات ويرفض أن “يفترض الوضع المحلي” نيابةً عنك.
- بشكل افتراضي، يرفض Gateway البدء ما لم يتم تعيين `gateway.mode=local` في `~/.openclaw/openclaw.json`. استخدم `--allow-unconfigured` للتشغيلات المخصصة/الخاصة بالتطوير.
- من المتوقع أن يكتب `openclaw onboard --mode local` و`openclaw setup` القيمة `gateway.mode=local`. إذا كان الملف موجودًا لكن `gateway.mode` مفقودًا، فاعتبر ذلك إعدادًا معطوبًا أو تم العبث به وأصلحه بدلًا من افتراض الوضع المحلي ضمنيًا.
- إذا كان الملف موجودًا وكانت `gateway.mode` مفقودة، فإن Gateway يعتبر ذلك تلفًا مريبًا في الإعداد ويرفض أن “يفترض الوضع المحلي” نيابةً عنك.
- يتم حظر الربط خارج loopback من دون مصادقة (حاجز أمان).
- يؤدي `SIGUSR1` إلى إعادة تشغيل داخل العملية عند السماح بذلك (`commands.restart` مفعّل افتراضيًا؛ اضبط `commands.restart: false` لحظر إعادة التشغيل اليدوية، مع بقاء gateway tool/config apply/update مسموحًا).
- تعمل معالجات `SIGINT`/`SIGTERM` على إيقاف عملية gateway، لكنها لا تستعيد أي حالة طرفية مخصصة. إذا كنت تغلف CLI باستخدام TUI أو إدخال raw-mode، فاستعد الطرفية قبل الخروج.
- يؤدّي `SIGUSR1` إلى إعادة تشغيل داخل العملية عند التفويض (`commands.restart` مفعّل افتراضيًا؛ اضبط `commands.restart: false` لمنع إعادة التشغيل اليدوية، مع بقاء gateway tool/config apply/update مسموحًا).
- تعمل معالجات `SIGINT`/`SIGTERM` على إيقاف عملية gateway، لكنها لا تستعيد أي حالة مخصصة للطرفية. إذا كنت تغلّف CLI باستخدام TUI أو إدخال raw-mode، فأعِد الطرفية إلى حالتها قبل الخروج.
### الخيارات
- `--port <port>`: منفذ WebSocket ‏(الافتراضي يأتي من الإعدادات/البيئة؛ وعادةً `18789`).
- `--port <port>`: منفذ WebSocket ‏(القيمة الافتراضية تأتي من config/env؛ وعادةً تكون `18789`).
- `--bind <loopback|lan|tailnet|auto|custom>`: وضع ربط المستمع.
- `--auth <token|password>`: تجاوز وضع المصادقة.
- `--token <token>`: تجاوز الرمز المميز (ويعيّن أيضًا `OPENCLAW_GATEWAY_TOKEN` للعملية).
- `--password <password>`: تجاوز كلمة المرور. تحذير: قد تنكشف كلمات المرور المضمنة ضمن قوائم العمليات المحلية.
- `--password-file <path>`: اقرأ كلمة مرور gateway من ملف.
- `--auth <token|password>`: تجاوز لوضع المصادقة.
- `--token <token>`: تجاوز للرمز المميز (ويعيّن أيضًا `OPENCLAW_GATEWAY_TOKEN` لهذه العملية).
- `--password <password>`: تجاوز لكلمة المرور. تحذير: قد تظهر كلمات المرور المضمّنة مباشرةً في قوائم العمليات المحلية.
- `--password-file <path>`: قراءة كلمة مرور gateway من ملف.
- `--tailscale <off|serve|funnel>`: كشف Gateway عبر Tailscale.
- `--tailscale-reset-on-exit`: إعادة تعيين إعداد serve/funnel في Tailscale عند الإيقاف.
- `--allow-unconfigured`: السماح ببدء gateway من دون `gateway.mode=local` في الإعدادات. يتجاوز هذا حاجز بدء التشغيل فقط من أجل التمهيد المخصص/التطويري؛ ولا يكتب ملف الإعدادات أو يصلحه.
- `--dev`: أنشئ إعدادات + مساحة عمل للتطوير إذا كانت مفقودة (يتجاوز `BOOTSTRAP.md`).
- `--reset`: أعد تعيين إعدادات التطوير + بيانات الاعتماد + الجلسات + مساحة العمل (يتطلب `--dev`).
- `--force`: اقتل أي مستمع موجود على المنفذ المحدد قبل البدء.
- `--verbose`: سجلات مطولة.
- `--cli-backend-logs`: اعرض فقط سجلات الواجهة الخلفية لـ CLI في الطرفية (ومع تمكين stdout/stderr).
- `--tailscale-reset-on-exit`: إعادة تعيين إعدادات Tailscale serve/funnel عند الإيقاف.
- `--allow-unconfigured`: السماح ببدء gateway من دون `gateway.mode=local` في الإعداد. هذا يتجاوز حاجز بدء التشغيل لأغراض الإقلاع المخصص/التطوير فقط؛ ولا يكتب ملف الإعداد أو يصلحه.
- `--dev`: إنشاء إعداد + مساحة عمل للتطوير إذا لم يكونا موجودين (يتخطى `BOOTSTRAP.md`).
- `--reset`: إعادة تعيين إعداد التطوير + بيانات الاعتماد + الجلسات + مساحة العمل (يتطلب `--dev`).
- `--force`: إنهاء أي مستمع موجود على المنفذ المحدد قبل البدء.
- `--verbose`: سجلات تفصيلية.
- `--cli-backend-logs`: عرض سجلات الواجهة الخلفية لـ CLI فقط في وحدة التحكم (مع تفعيل stdout/stderr).
- `--ws-log <auto|full|compact>`: نمط سجل websocket ‏(الافتراضي `auto`).
- `--compact`: اسم بديل لـ `--ws-log compact`.
- `--raw-stream`: سجّل أحداث بث النموذج الخام إلى jsonl.
- `--raw-stream-path <path>`: مسار jsonl للبث الخام.
- `--raw-stream`: تسجيل أحداث تدفق النموذج الخام إلى jsonl.
- `--raw-stream-path <path>`: مسار jsonl للتدفق الخام.
تحليل بدء التشغيل:
- اضبط `OPENCLAW_GATEWAY_STARTUP_TRACE=1` لتسجيل توقيتات المراحل أثناء بدء Gateway.
- شغّل `pnpm test:startup:gateway -- --runs 5 --warmup 1` لقياس أداء بدء Gateway. يسجل القياس أول خرج للعملية، و`/healthz`، و`/readyz`، وتوقيتات تتبع بدء التشغيل.
- عيّن `OPENCLAW_GATEWAY_STARTUP_TRACE=1` لتسجيل توقيتات المراحل أثناء بدء تشغيل Gateway.
- شغّل `pnpm test:startup:gateway -- --runs 5 --warmup 1` لقياس أداء بدء تشغيل Gateway. يسجّل القياس أول مخرجات للعملية، و`/healthz`، و`/readyz`، وتوقيتات تتبّع بدء التشغيل.
## الاستعلام عن Gateway قيد التشغيل
تستخدم جميع أوامر الاستعلام WebSocket RPC.
تستخدم كل أوامر الاستعلام WebSocket RPC.
أوضاع الخرج:
أوضاع الإخراج:
- الافتراضي: قابل للقراءة البشرية (وملوّن في TTY).
- الافتراضي: مقروء للبشر (وملوّن في TTY).
- `--json`: JSON قابل للقراءة آليًا (من دون تنسيق/مؤشر دوران).
- `--no-color` (أو `NO_COLOR=1`): تعطيل ANSI مع الحفاظ على التخطيط البشري.
- `--no-color` (أو `NO_COLOR=1`): تعطيل ANSI مع الإبقاء على التخطيط البشري.
الخيارات المشتركة (عند الدعم):
- `--url <url>`: عنوان URL الخاص بـ Gateway WebSocket.
- `--url <url>`: عنوان WebSocket الخاص بـ Gateway.
- `--token <token>`: رمز Gateway المميز.
- `--password <password>`: كلمة مرور Gateway.
- `--timeout <ms>`: المهلة/الميزانية (تختلف حسب الأمر).
- `--expect-final`: انتظر استجابة “نهائية” (استدعاءات الوكيل).
- `--timeout <ms>`: المهلة/الميزانية الزمنية (تختلف حسب الأمر).
- `--expect-final`: الانتظار للحصول على استجابة “نهائية” (استدعاءات الوكيل).
ملاحظة: عندما تضبط `--url`، لا يعود CLI إلى بيانات الاعتماد من الإعدادات أو البيئة.
مرّر `--token` أو `--password` صراحةً. غياب بيانات الاعتماد الصريحة هو خطأ.
ملاحظة: عند تعيين `--url`، لا يعود CLI إلى بيانات الاعتماد من config أو البيئة.
مرّر `--token` أو `--password` صراحةً. ويُعد غياب بيانات الاعتماد الصريحة خطأً.
### `gateway health`
@ -102,7 +102,7 @@ openclaw gateway run
openclaw gateway health --url ws://127.0.0.1:18789
```
تُعد نقطة النهاية HTTP ‏`/healthz` فحصًا للحيوية: فهي تستجيب بمجرد أن يتمكن الخادم من الرد على HTTP. أما نقطة النهاية HTTP ‏`/readyz` فهي أكثر صرامة وتبقى حمراء بينما لا تزال العمليات الجانبية عند بدء التشغيل، أو القنوات، أو Hooks المُعدّة تستقر.
تُعد نقطة النهاية HTTP ‏`/healthz` مسبار حيوية: إذ تُرجع الاستجابة بمجرد أن يتمكن الخادم من الرد عبر HTTP. أما نقطة النهاية HTTP ‏`/readyz` فهي أكثر صرامة وتظل غير جاهزة أثناء استقرار العمليات الجانبية عند بدء التشغيل، أو القنوات، أو الخطافات المضبوطة.
### `gateway usage-cost`
@ -116,11 +116,11 @@ openclaw gateway usage-cost --json
الخيارات:
- `--days <days>`: عدد الأيام المراد تضمينها (الافتراضي `30`).
- `--days <days>`: عدد الأيام التي يجب تضمينها (الافتراضي `30`).
### `gateway stability`
اجلب مسجل الثبات التشخيصي الأخير من Gateway قيد التشغيل.
اجلب مُسجّل الاستقرار التشخيصي الأخير من Gateway قيد التشغيل.
```bash
openclaw gateway stability
@ -132,22 +132,21 @@ openclaw gateway stability --json
الخيارات:
- `--limit <limit>`: الحد الأقصى لعدد الأحداث الأخيرة المراد تضمينها (الافتراضي `25`، الحد الأقصى `1000`).
- `--limit <limit>`: الحد الأقصى لعدد الأحداث الأخيرة التي يجب تضمينها (الافتراضي `25`، والحد الأقصى `1000`).
- `--type <type>`: التصفية حسب نوع الحدث التشخيصي، مثل `payload.large` أو `diagnostic.memory.pressure`.
- `--since-seq <seq>`: تضمين الأحداث بعد رقم التسلسل التشخيصي فقط.
- `--bundle [path]`: اقرأ حزمة ثبات محفوظة بدلًا من استدعاء Gateway قيد التشغيل. استخدم `--bundle latest` (أو فقط `--bundle`) لأحدث حزمة تحت دليل الحالة، أو مرّر مسار JSON للحزمة مباشرةً.
- `--export`: اكتب ملف zip تشخيصات دعم قابلًا للمشاركة بدلًا من طباعة تفاصيل الثبات.
- `--output <path>`: مسار الخرج لـ `--export`.
- `--since-seq <seq>`: تضمين الأحداث التي تلي رقم التسلسل التشخيصي فقط.
- `--bundle [path]`: قراءة حزمة استقرار محفوظة بدلًا من استدعاء Gateway قيد التشغيل. استخدم `--bundle latest` (أو فقط `--bundle`) لأحدث حزمة ضمن دليل الحالة، أو مرّر مباشرةً مسار JSON للحزمة.
- `--export`: كتابة ملف zip تشخيصي قابل للمشاركة بدلًا من طباعة تفاصيل الاستقرار.
- `--output <path>`: مسار الإخراج لـ `--export`.
ملاحظات:
- يكون المسجل نشطًا افتراضيًا ومن دون حمولة: فهو يلتقط البيانات الوصفية التشغيلية فقط، وليس نص الدردشة، أو مخرجات الأدوات، أو نصوص الطلبات أو الردود الخام. اضبط `diagnostics.enabled: false` فقط عندما تحتاج إلى تعطيل جمع Heartbeat التشخيصي الخاص بـ Gateway بالكامل.
- تحتفظ السجلات بالبيانات الوصفية التشغيلية: أسماء الأحداث، والأعداد، وأحجام البايتات، وقراءات الذاكرة، وحالة الطابور/الجلسة، وأسماء القنوات/Plugin، وملخصات الجلسات المنقّحة. وهي لا تحتفظ بنص الدردشة، أو أجسام Webhook، أو مخرجات الأدوات، أو أجسام الطلبات أو الردود الخام، أو الرموز المميزة، أو Cookies، أو القيم السرية، أو أسماء المضيفين، أو معرّفات الجلسات الخام.
- عند الخروج القاتل لـ Gateway، أو انتهاء مهلات الإيقاف، أو فشل بدء التشغيل بعد إعادة التشغيل، يكتب OpenClaw اللقطة التشخيصية نفسها إلى `~/.openclaw/logs/stability/openclaw-stability-*.json` عندما يحتوي المسجل على أحداث. افحص أحدث حزمة باستخدام `openclaw gateway stability --bundle latest`؛ وتنطبق أيضًا `--limit` و`--type` و`--since-seq` على خرج الحزمة.
- تحتفظ السجلات ببيانات تشغيلية وصفية: أسماء الأحداث، والعدادات، وأحجام البايتات، وقراءات الذاكرة، وحالة الطابور/الجلسة، وأسماء القنوات/Plugin، وملخصات الجلسات المنقّحة. وهي لا تحتفظ بنص الدردشة، أو أجسام Webhook، أو مخرجات الأدوات، أو أجسام الطلبات أو الاستجابات الخام، أو الرموز المميزة، أو ملفات تعريف الارتباط، أو القيم السرية، أو أسماء المضيفين، أو معرّفات الجلسات الخام. عيّن `diagnostics.enabled: false` لتعطيل المُسجّل بالكامل.
- عند حالات خروج Gateway الفادحة، ومهل الإيقاف، وإخفاقات بدء التشغيل عند إعادة التشغيل، يكتب OpenClaw اللقطة التشخيصية نفسها إلى `~/.openclaw/logs/stability/openclaw-stability-*.json` عندما يحتوي المُسجّل على أحداث. افحص أحدث حزمة باستخدام `openclaw gateway stability --bundle latest`؛ كما تنطبق `--limit` و`--type` و`--since-seq` أيضًا على إخراج الحزمة.
### `gateway diagnostics export`
اكتب ملف zip تشخيصات محلي مصممًا لإرفاقه بتقارير الأخطاء.
اكتب ملف zip تشخيصيًا محليًا مُصممًا لإرفاقه بتقارير الأخطاء.
```bash
openclaw gateway diagnostics export
@ -157,23 +156,23 @@ openclaw gateway diagnostics export --json
الخيارات:
- `--output <path>`: مسار zip للخرج. يكون افتراضيًا تصدير دعم تحت دليل الحالة.
- `--log-lines <count>`: الحد الأقصى لأسطر السجلات المنقحة المراد تضمينها (الافتراضي `5000`).
- `--log-bytes <bytes>`: الحد الأقصى لبايتات السجل المراد فحصها (الافتراضي `1000000`).
- `--url <url>`: عنوان URL الخاص بـ Gateway WebSocket للّقطة الصحية.
- `--output <path>`: مسار zip للإخراج. تكون القيمة الافتراضية تصدير دعم ضمن دليل الحالة.
- `--log-lines <count>`: الحد الأقصى لأسطر السجل المنقّحة التي يجب تضمينها (الافتراضي `5000`).
- `--log-bytes <bytes>`: الحد الأقصى لبايتات السجل التي يجب فحصها (الافتراضي `1000000`).
- `--url <url>`: عنوان WebSocket الخاص بـ Gateway للّقطة الصحية.
- `--token <token>`: رمز Gateway المميز للّقطة الصحية.
- `--password <password>`: كلمة مرور Gateway للّقطة الصحية.
- `--timeout <ms>`: مهلة لقطة الحالة/الصحة (الافتراضي `3000`).
- `--no-stability-bundle`: تخطَّ البحث عن حزمة الثبات المحفوظة.
- `--json`: اطبع المسار المكتوب، والحجم، وmanifest كـ JSON.
- `--no-stability-bundle`: تخطّي البحث عن حزمة الاستقرار المحفوظة.
- `--json`: طباعة المسار المكتوب، والحجم، والبيان الوصفي بصيغة JSON.
يحتوي التصدير على manifest، وملخص Markdown، وشكل الإعدادات، وتفاصيل الإعدادات المنقحة، وملخصات السجلات المنقحة، ولقطات الحالة/الصحة المنقحة الخاصة بـ Gateway، وأحدث حزمة ثبات عند وجودها.
يحتوي التصدير على بيان وصفي، وملخص Markdown، وبنية config، وتفاصيل config منقّحة، وملخصات سجلات منقّحة، ولقطات حالة/صحة Gateway منقّحة، وأحدث حزمة استقرار عند وجودها.
وهو مخصص للمشاركة. ويحتفظ بالتفاصيل التشغيلية التي تساعد في تصحيح الأخطاء، مثل حقول سجلات OpenClaw الآمنة، وأسماء الأنظمة الفرعية، ورموز الحالة، والمدد، والأوضاع المضبوطة، والمنافذ، ومعرّفات Plugin، ومعرّفات المزوّدين، وإعدادات الميزات غير السرية، ورسائل السجل التشغيلية المنقحة. ويحذف أو ينقّح نص الدردشة، وأجسام Webhook، ومخرجات الأدوات، وبيانات الاعتماد، وCookies، ومعرّفات الحسابات/الرسائل، ونصوص prompts/instructions، وأسماء المضيفين، والقيم السرية. عندما تبدو رسالة على نمط LogTape وكأنها نص حمولة مستخدم/دردشة/أداة، يحتفظ التصدير فقط بمعلومة أن رسالة ما قد حُذفت مع عدد بايتاتها.
وهو مخصص للمشاركة. ويحتفظ بتفاصيل تشغيلية تساعد على تصحيح الأخطاء، مثل حقول سجلات OpenClaw الآمنة، وأسماء الأنظمة الفرعية، ورموز الحالة، والمدد الزمنية، والأوضاع المضبوطة، والمنافذ، ومعرّفات Plugin، ومعرّفات الموفّرين، وإعدادات الميزات غير السرية، ورسائل السجل التشغيلية المنقّحة. كما يحذف أو ينقّح نص الدردشة، وأجسام Webhook، ومخرجات الأدوات، وبيانات الاعتماد، وملفات تعريف الارتباط، ومعرّفات الحساب/الرسائل، ونصوص المطالبات/التعليمات، وأسماء المضيفين، والقيم السرية. عندما تبدو رسالة بأسلوب LogTape كأنها نص حمولة مستخدم/دردشة/أداة، يحتفظ التصدير فقط بوجود رسالة محذوفة مع عدد بايتاتها.
### `gateway status`
يعرض `gateway status` خدمة Gateway ‏(`launchd/systemd/schtasks`) بالإضافة إلى فحص اختياري للاتصال/قدرة المصادقة.
يعرض `gateway status` خدمة Gateway ‏(`launchd/systemd/schtasks`) بالإضافة إلى فحص اختياري لإمكانات الاتصال/المصادقة.
```bash
openclaw gateway status
@ -183,43 +182,42 @@ openclaw gateway status --require-rpc
الخيارات:
- `--url <url>`: أضف هدف فحص صريحًا. لا يزال يتم فحص البعيد المضبوط + localhost.
- `--token <token>`: مصادقة الرمز المميز للفحص.
- `--password <password>`: مصادقة كلمة المرور للفحص.
- `--url <url>`: إضافة هدف فحص صريح. ولا يزال يتم فحص الهدف البعيد المضبوط + localhost.
- `--token <token>`: مصادقة بالرمز المميز للفحص.
- `--password <password>`: مصادقة بكلمة المرور للفحص.
- `--timeout <ms>`: مهلة الفحص (الافتراضي `10000`).
- `--no-probe`: تخطَّ فحص الاتصال (عرض الخدمة فقط).
- `--deep`: افحص أيضًا الخدمات على مستوى النظام.
- `--require-rpc`: ارفع فحص الاتصال الافتراضي إلى فحص قراءة، واخرج بقيمة غير صفرية عند فشل فحص القراءة هذا. لا يمكن دمجه مع `--no-probe`.
- `--no-probe`: تخطّي فحص الاتصال (عرض الخدمة فقط).
- `--deep`: فحص خدمات على مستوى النظام أيضًا.
- `--require-rpc`: ترقية فحص الاتصال الافتراضي إلى فحص قراءة، والخروج برمز غير صفري عند فشل فحص القراءة هذا. لا يمكن دمجه مع `--no-probe`.
ملاحظات:
- يظل `gateway status` متاحًا للتشخيص حتى عندما تكون إعدادات CLI المحلية مفقودة أو غير صالحة.
- يثبت `gateway status` الافتراضي حالة الخدمة، واتصال WebSocket، وقدرة المصادقة المرئية وقت Handshake. لكنه لا يثبت عمليات القراءة/الكتابة/الإدارة.
- يقوم `gateway status` بتحليل SecretRefs الخاصة بالمصادقة المضبوطة لاستخدامها في مصادقة الفحص عندما يكون ذلك ممكنًا.
- إذا تعذر تحليل SecretRef مطلوبة للمصادقة في مسار هذا الأمر، فسيعرض `gateway status --json` القيمة `rpc.authWarning` عند فشل فحص الاتصال/المصادقة؛ مرّر `--token`/`--password` صراحةً أو قم أولًا بتحليل مصدر السر.
- إذا نجح الفحص، فسيتم إخفاء تحذيرات auth-ref غير المحلولة لتجنب النتائج الإيجابية الكاذبة.
- استخدم `--require-rpc` في النصوص البرمجية والأتمتة عندما لا يكفي وجود خدمة تستمع وتحتاج أيضًا إلى أن تكون استدعاءات RPC ذات نطاق القراءة سليمة.
- يضيف `--deep` فحصًا بأفضل جهد لتثبيتات `launchd/systemd/schtasks` الإضافية. عند اكتشاف عدة خدمات شبيهة بـ gateway، يطبع الخرج البشري تلميحات للتنظيف ويحذر من أن معظم الإعدادات يجب أن تشغّل gateway واحدة لكل جهاز.
- يتضمن الخرج البشري مسار سجل الملف المحلول بالإضافة إلى لقطة لمسارات/صلاحية الإعدادات بين CLI والخدمة للمساعدة في تشخيص انجراف ملف التعريف أو دليل الحالة.
- في تثبيتات Linux systemd، تقرأ فحوصات انجراف مصادقة الخدمة قيم `Environment=` و`EnvironmentFile=` من الوحدة (بما في ذلك `%h`، والمسارات المقتبسة، والملفات المتعددة، وملفات `-` الاختيارية).
- تقوم فحوصات الانجراف بتحليل SecretRefs الخاصة بـ `gateway.auth.token` باستخدام بيئة وقت التشغيل المدمجة (بيئة أمر الخدمة أولًا، ثم احتياط بيئة العملية).
- إذا لم تكن مصادقة الرمز المميز نشطة فعليًا (ضبط صريح لـ `gateway.auth.mode` على `password`/`none`/`trusted-proxy`، أو كان الوضع غير مضبوط حيث يمكن لكلمة المرور أن تفوز ولا يوجد مرشح رمز مميز يمكنه الفوز)، فتتخطى فحوصات انجراف الرمز تحليل رمز الإعدادات.
- يظل `gateway status` متاحًا لأغراض التشخيص حتى عندما يكون إعداد CLI المحلي مفقودًا أو غير صالح.
- يثبت `gateway status` الافتراضي حالة الخدمة، واتصال WebSocket، وإمكانات المصادقة الظاهرة وقت المصافحة. لكنه لا يثبت عمليات القراءة/الكتابة/الإدارة.
- يحل `gateway status` مراجع SecretRef المضبوطة للمصادقة الخاصة بالفحص عندما يكون ذلك ممكنًا.
- إذا تعذر حل SecretRef مطلوب للمصادقة في مسار هذا الأمر، فإن `gateway status --json` يبلغ عن `rpc.authWarning` عند فشل اتصال/مصادقة الفحص؛ مرّر `--token`/`--password` صراحةً أو عالج مصدر السر أولًا.
- إذا نجح الفحص، يتم كتم تحذيرات auth-ref غير المحلولة لتجنب النتائج الإيجابية الكاذبة.
- استخدم `--require-rpc` في السكربتات والأتمتة عندما لا تكفي خدمة تستمع فقط، وتحتاج أيضًا إلى أن تكون استدعاءات RPC ضمن نطاق القراءة سليمة.
- يضيف `--deep` فحصًا بأفضل جهد لتثبيتات `launchd/systemd/schtasks` الإضافية. وعند اكتشاف خدمات متعددة شبيهة بـ gateway، يطبع الإخراج البشري تلميحات للتنظيف ويحذّر من أن معظم الإعدادات يجب أن تشغّل gateway واحدًا لكل جهاز.
- يتضمن الإخراج البشري مسار سجل الملف المحلول بالإضافة إلى لقطة لمسارات/صلاحية إعداد CLI مقابل إعداد الخدمة للمساعدة في تشخيص انجراف ملف التعريف أو دليل الحالة.
- في تثبيتات Linux systemd، تقرأ فحوصات انجراف مصادقة الخدمة قيم `Environment=` و`EnvironmentFile=` من الوحدة (بما في ذلك `%h`، والمسارات بين علامات اقتباس، والملفات المتعددة، والملفات الاختيارية `-`).
- تعالج فحوصات الانجراف مراجع SecretRef الخاصة بـ `gateway.auth.token` باستخدام بيئة التشغيل المدمجة (بيئة أمر الخدمة أولًا، ثم بيئة العملية كخيار احتياطي).
- إذا لم تكن مصادقة الرمز المميز فعّالة بالفعل (عند وجود `gateway.auth.mode` صريح بقيمة `password` أو `none` أو `trusted-proxy`، أو عند ترك الوضع غير معيّن حيث يمكن أن تتغلب كلمة المرور ولا يوجد مرشح رمز مميز يمكن أن يتغلب)، فإن فحوصات انجراف الرمز المميز تتخطى حل رمز config.
### `gateway probe`
يُعد `gateway probe` أمر “تصحيح كل شيء”. فهو يفحص دائمًا:
- الـ Gateway البعيد المضبوط لديك (إذا كان مضبوطًا)، و
- localhost ‏(loopback) **حتى إذا كان البعيد مضبوطًا**.
- الـ gateway البعيد المضبوط لديك (إن وُجد)، و
- localhost ‏(loopback) **حتى إذا كان الهدف البعيد مضبوطًا**.
إذا مرّرت `--url`، فسيُضاف هذا الهدف الصريح قبل كليهما. يضع الخرج البشري تسميات على
الأهداف على النحو التالي:
إذا مرّرت `--url`، فسيُضاف هذا الهدف الصريح قبل كليهما. يضع الإخراج البشري تسميات للأهداف على النحو التالي:
- `URL (explicit)`
- `Remote (configured)` أو `Remote (configured, inactive)`
- `local loopback`
- `Local loopback`
إذا كان يمكن الوصول إلى عدة Gateways، فسيطبعها جميعًا. تُدعم عدة Gateways عندما تستخدم ملفات تعريف/منافذ معزولة (مثل rescue bot)، لكن معظم التثبيتات لا تزال تشغّل gateway واحدة.
إذا أمكن الوصول إلى عدة Gateways، فسيعرضها جميعًا. تُدعم تعدد Gateways عندما تستخدم ملفات تعريف/منافذ معزولة (مثل rescue bot)، لكن معظم التثبيتات لا تزال تشغّل gateway واحدًا.
```bash
openclaw gateway probe
@ -228,41 +226,41 @@ openclaw gateway probe --json
التفسير:
- تعني `Reachable: yes` أن هدفًا واحدًا على الأقل قبل اتصال WebSocket.
- يوضح `Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only` ما الذي استطاع الفحص إثباته بخصوص المصادقة. وهو منفصل عن قابلية الوصول.
- تعني `Read probe: ok` أن استدعاءات RPC التفصيلية ذات نطاق القراءة (`health`/`status`/`system-presence`/`config.get`) نجحت أيضًا.
- تعني `Read probe: limited - missing scope: operator.read` أن الاتصال نجح لكن RPC ذات نطاق القراءة محدودة. ويُبلّغ عن ذلك على أنه قابلية وصول **متدهورة**، وليس فشلًا كاملًا.
- تكون قيمة الخروج غير صفرية فقط عندما لا يكون أي هدف من الأهداف المفحوصة قابلًا للوصول.
- `Reachable: yes` يعني أن هدفًا واحدًا على الأقل قبل اتصال WebSocket.
- `Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only` يوضح ما الذي استطاع الفحص إثباته بشأن المصادقة. وهو منفصل عن إمكانية الوصول.
- `Read probe: ok` يعني أن استدعاءات RPC التفصيلية ضمن نطاق القراءة (`health`/`status`/`system-presence`/`config.get`) نجحت أيضًا.
- `Read probe: limited - missing scope: operator.read` يعني أن الاتصال نجح لكن RPC ضمن نطاق القراءة محدود. ويُبلّغ عن ذلك بوصفه إمكانية وصول **متدهورة**، وليس فشلًا كاملًا.
- يكون رمز الخروج غير صفري فقط عندما لا يمكن الوصول إلى أي هدف تم فحصه.
ملاحظات JSON ‏(`--json`):
- المستوى الأعلى:
- `ok`: يمكن الوصول إلى هدف واحد على الأقل.
- `degraded`: كان لدى هدف واحد على الأقل RPC تفصيلي محدود النطاق.
- `capability`: أفضل قدرة شوهدت عبر الأهداف القابلة للوصول (`read_only` أو `write_capable` أو `admin_capable` أو `pairing_pending` أو `connected_no_operator_scope` أو `unknown`).
- `primaryTargetId`: أفضل هدف للتعامل معه كفائز نشط وفق هذا الترتيب: عنوان URL الصريح، ثم SSH tunnel، ثم البعيد المضبوط، ثم local loopback.
- `capability`: أفضل قدرة جرى رصدها عبر الأهداف القابلة للوصول (`read_only` أو `write_capable` أو `admin_capable` أو `pairing_pending` أو `connected_no_operator_scope` أو `unknown`).
- `primaryTargetId`: أفضل هدف يجب التعامل معه بوصفه الفائز النشط وفق هذا الترتيب: عنوان URL الصريح، أو نفق SSH، أو الهدف البعيد المضبوط، ثم local loopback.
- `warnings[]`: سجلات تحذير بأفضل جهد تحتوي على `code` و`message` و`targetIds` اختيارية.
- `network`: تلميحات عناوين URL الخاصة بـ local loopback/‏tailnet مشتقة من الإعدادات الحالية وشبكة المضيف.
- `discovery.timeoutMs` و`discovery.count`: ميزانية/عدد نتائج الاكتشاف الفعلية المستخدمة في تمريرة الفحص هذه.
- `network`: تلميحات عناوين URL الخاصة بـ local loopback/tailnet والمشتقة من الإعداد الحالي وشبكة المضيف.
- `discovery.timeoutMs` و`discovery.count`: ميزانية/عدد نتائج الاكتشاف الفعلية المستخدمة في جولة الفحص هذه.
- لكل هدف (`targets[].connect`):
- `ok`: القابلية للوصول بعد الاتصال + تصنيف التدهور.
- `rpcOk`: نجاح RPC التفصيلي الكامل.
- `scopeLimited`: فشل RPC التفصيلي بسبب غياب نطاق المشغّل.
- `ok`: إمكانية الوصول بعد الاتصال + تصنيف الحالة المتدهورة.
- `rpcOk`: نجاح كامل لـ RPC التفصيلي.
- `scopeLimited`: فشل RPC التفصيلي بسبب غياب نطاق operator.
- لكل هدف (`targets[].auth`):
- `role`: دور المصادقة المُبلّغ عنه في `hello-ok` عند توفره.
- `scopes`: النطاقات الممنوحة المُبلّغ عنها في `hello-ok` عند توفرها.
- `role`: دور المصادقة المُبلغ عنه في `hello-ok` عند توفره.
- `scopes`: النطاقات الممنوحة والمُبلغ عنها في `hello-ok` عند توفرها.
- `capability`: تصنيف قدرة المصادقة المعروض لذلك الهدف.
رموز التحذير الشائعة:
- `ssh_tunnel_failed`: فشل إعداد SSH tunnel؛ وعاد الأمر إلى الفحوصات المباشرة.
- `multiple_gateways`: أمكن الوصول إلى أكثر من هدف واحد؛ وهذا غير معتاد إلا إذا كنت تشغّل عمدًا ملفات تعريف معزولة، مثل rescue bot.
- `auth_secretref_unresolved`: تعذر تحليل SecretRef مصادقة مضبوطة لهدف فاشل.
- `ssh_tunnel_failed`: فشل إعداد نفق SSH؛ وعاد الأمر إلى الفحوصات المباشرة.
- `multiple_gateways`: أمكن الوصول إلى أكثر من هدف واحد؛ وهذا غير معتاد ما لم تكن تشغّل عمدًا ملفات تعريف معزولة، مثل rescue bot.
- `auth_secretref_unresolved`: تعذر حل SecretRef مصادقة مضبوطة لهدف فاشل.
- `probe_scope_limited`: نجح اتصال WebSocket، لكن فحص القراءة كان محدودًا بسبب غياب `operator.read`.
#### البعيد عبر SSH ‏(تكافؤ تطبيق Mac)
#### الاتصال البعيد عبر SSH ‏(تكافؤ تطبيق Mac)
يستخدم وضع “Remote over SSH” في تطبيق macOS إعادة توجيه منفذ محلية بحيث يصبح gateway البعيد (الذي قد يكون مربوطًا بـ loopback فقط) قابلًا للوصول على `ws://127.0.0.1:<port>`.
يستخدم وضع “Remote over SSH” في تطبيق macOS إعادة توجيه منفذ محليًا بحيث يصبح الـ gateway البعيد (الذي قد يكون مربوطًا بـ loopback فقط) قابلًا للوصول عند `ws://127.0.0.1:<port>`.
المكافئ في CLI:
@ -272,13 +270,13 @@ openclaw gateway probe --ssh user@gateway-host
الخيارات:
- `--ssh <target>`: ‏`user@host` أو `user@host:port` ‏(المنفذ افتراضيًا `22`).
- `--ssh <target>`: ‏`user@host` أو `user@host:port` ‏(المنفذ الافتراضي `22`).
- `--ssh-identity <path>`: ملف الهوية.
- `--ssh-auto`: اختر أول مضيف gateway مكتشف كهدف SSH من نقطة نهاية
الاكتشاف المحلولة (`local.` بالإضافة إلى المجال واسع النطاق المضبوط، إن وجد). يتم تجاهل
- `--ssh-auto`: اختيار أول مضيف gateway مكتشف بوصفه هدف SSH من نقطة نهاية
الاكتشاف المحلولة (`local.` بالإضافة إلى النطاق واسع النطاق المضبوط، إن وجد). يتم تجاهل
التلميحات المعتمدة على TXT فقط.
الإعدادات (اختيارية، وتُستخدم كقيم افتراضية):
الإعداد (اختياري، يُستخدم كقيم افتراضية):
- `gateway.remote.sshTarget`
- `gateway.remote.sshIdentity`
@ -294,7 +292,7 @@ openclaw gateway call logs.tail --params '{"sinceMs": 60000}'
الخيارات:
- `--params <json>`: سلسلة كائن JSON للمعاملات (الافتراضي `{}`)
- `--params <json>`: سلسلة كائن JSON للمعلمات (الافتراضي `{}`)
- `--url <url>`
- `--token <token>`
- `--password <password>`
@ -304,8 +302,8 @@ openclaw gateway call logs.tail --params '{"sinceMs": 60000}'
ملاحظات:
- يجب أن تكون `--params` بصيغة JSON صالحة.
- يُستخدم `--expect-final` أساسًا لاستدعاءات RPC بأسلوب الوكيل التي تبث أحداثًا وسيطة قبل الحمولة النهائية.
- يجب أن تكون قيمة `--params` بصيغة JSON صالحة.
- `--expect-final` مخصص أساسًا لاستدعاءات RPC بأسلوب الوكيل التي تبث أحداثًا وسيطة قبل حمولة نهائية.
## إدارة خدمة Gateway
@ -319,38 +317,38 @@ openclaw gateway uninstall
خيارات الأوامر:
- `gateway status`: ‏`--url` و`--token` و`--password` و`--timeout` و`--no-probe` و`--require-rpc` و`--deep` و`--json`
- `gateway install`: ‏`--port` و`--runtime <node|bun>` و`--token` و`--force` و`--json`
- `gateway status`: ‏`--url`، `--token`، `--password`، `--timeout`، `--no-probe`، `--require-rpc`، `--deep`، `--json`
- `gateway install`: ‏`--port`، `--runtime <node|bun>`، `--token`، `--force`، `--json`
- `gateway uninstall|start|stop|restart`: ‏`--json`
ملاحظات:
- يدعم `gateway install` الخيارات `--port` و`--runtime` و`--token` و`--force` و`--json`.
- عندما تتطلب مصادقة الرمز المميز وجود رمز وكان `gateway.auth.token` مُدارًا عبر SecretRef، فإن `gateway install` يتحقق من أن SecretRef قابلة للتحليل لكنه لا يحتفظ بالرمز المحلول داخل بيانات بيئة الخدمة الوصفية.
- إذا كانت مصادقة الرمز المميز تتطلب رمزًا وكان SecretRef الخاص بالرمز المضبوط غير قابل للتحليل، يفشل التثبيت بشكل مغلق بدلًا من حفظ نص صريح احتياطي.
- بالنسبة إلى مصادقة كلمة المرور في `gateway run`، ففضّل `OPENCLAW_GATEWAY_PASSWORD` أو `--password-file` أو `gateway.auth.password` المدعوم بـ SecretRef بدلًا من `--password` المضمن.
- في وضع المصادقة المستنتج، لا يؤدي `OPENCLAW_GATEWAY_PASSWORD` الموجود في shell فقط إلى تخفيف متطلبات رمز التثبيت؛ استخدم إعدادات دائمة (`gateway.auth.password` أو `env` في الإعدادات) عند تثبيت خدمة مُدارة.
- إذا كان كل من `gateway.auth.token` و`gateway.auth.password` مضبوطين وكانت `gateway.auth.mode` غير مضبوطة، فسيتم حظر التثبيت حتى يتم ضبط الوضع صراحةً.
- تقبل أوامر دورة الحياة `--json` لاستخدامها في السكربتات.
- عندما تتطلب مصادقة الرمز المميز وجود رمز مميز وكان `gateway.auth.token` مُدارًا عبر SecretRef، فإن `gateway install` يتحقق من إمكانية حل SecretRef لكنه لا يحفظ الرمز المميز المحلول في بيانات بيئة الخدمة الوصفية.
- إذا كانت مصادقة الرمز المميز تتطلب رمزًا مميزًا وكان SecretRef الخاص بالرمز المميز المضبوط غير محلول، يفشل التثبيت بشكل مغلق بدلًا من حفظ نص عادي احتياطي.
- لمصادقة كلمة المرور في `gateway run`، يُفضَّل استخدام `OPENCLAW_GATEWAY_PASSWORD` أو `--password-file` أو `gateway.auth.password` المدعوم عبر SecretRef بدلًا من `--password` المضمّن.
- في وضع المصادقة المستنتج، لا يؤدي `OPENCLAW_GATEWAY_PASSWORD` الموجود في shell فقط إلى تخفيف متطلبات رمز التثبيت المميز؛ استخدم إعدادًا دائمًا (`gateway.auth.password` أو `env` في config) عند تثبيت خدمة مُدارة.
- إذا كان كل من `gateway.auth.token` و`gateway.auth.password` مضبوطين وكانت `gateway.auth.mode` غير معيّنة، فسيتم حظر التثبيت حتى يُضبط الوضع صراحةً.
- تقبل أوامر دورة الحياة الخيار `--json` لأغراض السكربتات.
## اكتشاف Gateways ‏(Bonjour)
يقوم `gateway discover` بمسح إشارات Gateway ‏(`_openclaw-gw._tcp`).
يفحص `gateway discover` إشارات Gateway ‏(`_openclaw-gw._tcp`).
- DNS-SD متعدد الإرسال: `local.`
- DNS-SD أحادي الإرسال (Wide-Area Bonjour): اختر مجالًا (مثال: `openclaw.internal.`) واضبط split DNS + خادم DNS؛ راجع [/gateway/bonjour](/ar/gateway/bonjour)
- DNS-SD أحادي الإرسال (Wide-Area Bonjour): اختر نطاقًا (مثال: `openclaw.internal.`) وأعد split DNS + خادم DNS؛ راجع [/gateway/bonjour](/ar/gateway/bonjour)
فقط Gateways التي تم تفعيل اكتشاف Bonjour فيها (افتراضيًا) هي التي تعلن الإشارة.
فقط الـ Gateways التي تم تمكين اكتشاف Bonjour فيها (افتراضيًا) تعلن عن الإشارة.
تتضمن سجلات الاكتشاف واسع النطاق (TXT):
- `role` ‏(تلميح دور gateway)
- `transport` ‏(تلميح النقل، مثل `gateway`)
- `gatewayPort` ‏(منفذ WebSocket، وعادةً `18789`)
- `sshPort` ‏(اختياري؛ تفترض العملاء أن أهداف SSH الافتراضية هي `22` عند غيابه)
- `tailnetDns` ‏(اسم مضيف MagicDNS، عند توفره)
- `gatewayTls` / `gatewayTlsSha256` ‏(تفعيل TLS + بصمة الشهادة)
- `cliPath` ‏(تلميح التثبيت البعيد المكتوب إلى المنطقة واسعة النطاق)
- `role` (تلميح دور gateway)
- `transport` (تلميح النقل، مثل `gateway`)
- `gatewayPort` (منفذ WebSocket، وعادةً `18789`)
- `sshPort` (اختياري؛ تستخدم الأطراف العميلة `22` كهدف SSH افتراضي عند غيابه)
- `tailnetDns` (اسم مضيف MagicDNS، عند توفره)
- `gatewayTls` / `gatewayTlsSha256` (تمكين TLS + بصمة الشهادة)
- `cliPath` (تلميح التثبيت البعيد المكتوب إلى المنطقة واسعة النطاق)
### `gateway discover`
@ -361,7 +359,7 @@ openclaw gateway discover
الخيارات:
- `--timeout <ms>`: مهلة لكل أمر (browse/resolve)؛ الافتراضي `2000`.
- `--json`: خرج قابل للقراءة آليًا (ويعطل أيضًا التنسيق/مؤشر الدوران).
- `--json`: إخراج قابل للقراءة آليًا (ويعطّل أيضًا التنسيق/مؤشر الدوران).
أمثلة:
@ -372,9 +370,9 @@ openclaw gateway discover --json | jq '.beacons[].wsUrl'
ملاحظات:
- يقوم CLI بمسح `local.` بالإضافة إلى المجال واسع النطاق المضبوط عندما يكون مفعّلًا.
- يتم اشتقاق `wsUrl` في خرج JSON من نقطة نهاية الخدمة المحلولة، وليس من
- يفحص CLI النطاق `local.` بالإضافة إلى النطاق واسع النطاق المضبوط عندما يكون مفعّلًا.
- تُشتق `wsUrl` في إخراج JSON من نقطة نهاية الخدمة المحلولة، وليس من
التلميحات المعتمدة على TXT فقط مثل `lanHost` أو `tailnetDns`.
- في mDNS الخاص بـ `local.`، لا يتم بث `sshPort` و`cliPath` إلا عندما
تكون `discovery.mdns.mode` هي `full`. لا يزال DNS-SD واسع النطاق يكتب `cliPath`؛ كما يبقى `sshPort`
اختياريًا هناك أيضًا.
تكون `discovery.mdns.mode` مساوية لـ `full`. ولا يزال DNS-SD واسع النطاق يكتب `cliPath`؛
كما يبقى `sshPort` اختياريًا هناك أيضًا.

1621
docs/ar/cli/index.md
View File

File diff suppressed because it is too large Load Diff

292
docs/ar/cli/plugins.md
View File

@ -1,27 +1,27 @@
---
read_when:
- تريد تثبيت أو إدارة Plugins الخاصة بـ Gateway أو الحزم المتوافقة
- تريد تصحيح أخطاء فشل تحميل Plugin وإصلاحها
summary: مرجع CLI لـ `openclaw plugins` (list، install، marketplace، uninstall، enable/disable، doctor)
- تريد تثبيت أو إدارة Plugins الخاصة بـ Gateway أو الحِزم المتوافقة.
- تريد تصحيح أخطاء فشل تحميل Plugin.
summary: مرجع CLI لـ `openclaw plugins` (`list` و`install` و`marketplace` و`uninstall` و`enable/disable` و`doctor`)
title: plugins
x-i18n:
generated_at: "2026-04-23T07:23:15Z"
generated_at: "2026-04-23T13:58:32Z"
model: gpt-5.4
provider: openai
source_hash: 7dd521db1de47ceb183d98a538005d3d816f52ffeee12593bcbaa8014d6e507b
source_hash: 469364823c0766f6534c5d7eee963877f98fe23ecfa45251696a34ef65d57599
source_path: cli/plugins.md
workflow: 15
---
# `openclaw plugins`
إدارة Plugins الخاصة بـ Gateway، وحزم hook، والحزم المتوافقة.
إدارة Plugins الخاصة بـ Gateway، وحِزم الخطافات، والحِزم المتوافقة.
ذو صلة:
- نظام Plugin: [Plugins](/ar/tools/plugin)
- توافق الحزم: [حزم Plugin](/ar/plugins/bundles)
- بيان Plugin + المخطط: [بيان Plugin](/ar/plugins/manifest)
- توافق الحِزم: [حِزم Plugin](/ar/plugins/bundles)
- بيان Plugin والمخطط: [بيان Plugin](/ar/plugins/manifest)
- التقوية الأمنية: [الأمان](/ar/gateway/security)
## الأوامر
@ -46,24 +46,24 @@ openclaw plugins marketplace list <marketplace>
openclaw plugins marketplace list <marketplace> --json
```
تأتي Plugins المضمّنة مع OpenClaw. ويكون بعضها مفعّلًا افتراضيًا (مثل
موفري النماذج المضمّنين، وموفري الكلام المضمّنين، وPlugin المتصفح
المضمّن)؛ بينما يتطلب بعضها الآخر تشغيل `plugins enable`.
تأتي Plugins المضمّنة مع OpenClaw. يكون بعضها مفعّلًا افتراضيًا (على سبيل المثال
موفرو النماذج المضمّنون، وموفرو الكلام المضمّنون، وPlugin المتصفح
المضمّن)؛ بينما يتطلب البعض الآخر `plugins enable`.
يجب أن تأتي Plugins OpenClaw الأصلية مع `openclaw.plugin.json` يتضمن مخطط JSON
مضمنًا (`configSchema`، حتى لو كان فارغًا). أما الحزم المتوافقة فتستخدم
بيانات manifests الخاصة بحزمها بدلًا من ذلك.
يجب أن تتضمن Plugins الأصلية الخاصة بـ OpenClaw ملف `openclaw.plugin.json` مع
JSON Schema مضمن (`configSchema`، حتى لو كان فارغًا). أما الحِزم المتوافقة
فتستخدم بيانات الحزمة الخاصة بها بدلًا من ذلك.
يعرض `plugins list` قيمة `Format: openclaw` أو `Format: bundle`. كما يعرض
الإخراج المفصّل في list/info النوع الفرعي للحزمة (`codex` أو `claude` أو `cursor`) بالإضافة
إلى قدرات الحزمة المكتشفة.
يعرض `plugins list` القيمة `Format: openclaw` أو `Format: bundle`. كما يعرض خرج
القائمة/المعلومات المفصل النوع الفرعي للحزمة (`codex` أو `claude` أو `cursor`)
إضافة إلى قدرات الحزمة المكتشفة.
### Install
### التثبيت
```bash
openclaw plugins install <package> # ClawHub أولًا، ثم npm
openclaw plugins install clawhub:<package> # ClawHub فقط
openclaw plugins install <package> --force # الكتابة فوق تثبيت موجود
openclaw plugins install <package> --force # الكتابة فوق التثبيت الحالي
openclaw plugins install <package> --pin # تثبيت الإصدار
openclaw plugins install <package> --dangerously-force-unsafe-install
openclaw plugins install <path> # مسار محلي
@ -72,95 +72,95 @@ openclaw plugins install <plugin> --marketplace <name> # marketplace (صريح)
openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo>
```
تُفحص أسماء الحزم المجردة مقابل ClawHub أولًا، ثم npm. ملاحظة أمنية:
تعامل مع تثبيت Plugin كما تتعامل مع تشغيل تعليمات برمجية. ويفضّل استخدام إصدارات مثبّتة.
تُفحص أسماء الحِزم المجردة في ClawHub أولًا، ثم npm. ملاحظة أمنية:
تعامل مع تثبيت Plugins كما لو كنت تشغّل شيفرة. ويُفضّل استخدام إصدارات مثبّتة.
إذا كان قسم `plugins` لديك مدعومًا بملف `$include` أحادي الملف، فإن
`plugins install` و`plugins update` و`plugins enable` و`plugins disable` و`plugins uninstall`
تكتب إلى ذلك الملف المضمَّن وتترك `openclaw.json` من دون تغيير. أما
التضمينات الجذرية، ومصفوفات include، والتضمينات ذات التجاوزات الشقيقة
فتفشل بشكل مغلق بدلًا من التسطيح. راجع [تضمينات الإعدادات](/ar/gateway/configuration)
للاطلاع على الأشكال المدعومة.
إذا كان القسم `plugins` لديك يستند إلى `$include` أحادي الملف، فإن
`plugins install/update/enable/disable/uninstall` تكتب في ذلك الملف المضمّن
وتترك `openclaw.json` دون تعديل. وتفشل تضمينات الجذر، ومصفوفات التضمين،
والتضمينات التي تحتوي على تجاوزات مجاورة بشكل مغلق بدلًا من تسطيحها.
راجع [تضمينات التكوين](/ar/gateway/configuration) لمعرفة الأشكال المدعومة.
إذا كانت الإعدادات غير صالحة، فإن `plugins install` يفشل عادةً بشكل مغلق ويطلب منك
تشغيل `openclaw doctor --fix` أولًا. والاستثناء الموثق الوحيد هو مسار ضيق
لاستعادة Plugin مضمّن يختاره Plugin صراحةً عبر
إذا كان التكوين غير صالح، فإن `plugins install` يفشل عادة بشكل مغلق ويطلب منك
تشغيل `openclaw doctor --fix` أولًا. والاستثناء الموثق الوحيد هو مسار
استرداد ضيق لPlugin مضمّن يختاره صراحةً
`openclaw.install.allowInvalidConfigRecovery`.
يعيد `--force` استخدام هدف التثبيت الحالي ويكتب فوق Plugin أو حزمة hook
مثبتة بالفعل في مكانها. استخدمه عندما تقصد عمدًا إعادة تثبيت المعرّف نفسه
من مسار محلي جديد، أو أرشيف، أو حزمة ClawHub، أو عنصر npm.
أما للترقيات المعتادة لـ Plugin npm مُتتبَّع بالفعل، ففضّل
يعيد `--force` استخدام هدف التثبيت الحالي ويكتب فوق Plugin أو حزمة خطافات
مثبتة مسبقًا في مكانها. استخدمه عندما تكون بصدد إعادة تثبيت
المعرّف نفسه عمدًا من مسار محلي جديد، أو أرشيف، أو حزمة ClawHub، أو
مكوّن npm. أما للترقيات الاعتيادية لـ Plugin npm متتبَّع مسبقًا، ففضّل
`openclaw plugins update <id-or-npm-spec>`.
إذا شغّلت `plugins install` لمعرّف Plugin مثبت بالفعل، فسيتوقف OpenClaw
ويوجهك إلى `plugins update <id-or-npm-spec>` للترقية المعتادة،
إذا شغّلت `plugins install` لمعرّف Plugin مثبت بالفعل، فإن OpenClaw
يتوقف ويوجهك إلى `plugins update <id-or-npm-spec>` للترقية المعتادة،
أو إلى `plugins install <package> --force` عندما تريد فعلًا الكتابة فوق
التثبيت الحالي من مصدر مختلف.
ينطبق `--pin` على تثبيتات npm فقط. وهو غير مدعوم مع `--marketplace`,
لأن تثبيتات marketplace تحفظ بيانات وصفية لمصدر marketplace بدلًا من
ينطبق `--pin` على تثبيتات npm فقط. وهو غير مدعوم مع `--marketplace`،
لأن تثبيتات marketplace تحفظ بيانات مصدر marketplace بدلًا من
مواصفة npm.
يُعد `--dangerously-force-unsafe-install` خيار كسر زجاج للحالات الإيجابية
الخاطئة في ماسح التعليمات البرمجية الخطرة المدمج. فهو يسمح باستمرار التثبيت
حتى عندما يبلّغ الماسح المدمج عن نتائج `critical`، لكنه **لا**
يتجاوز كتل سياسة hook الخاصة بـ Plugin `before_install` و**لا** يتجاوز
إخفاقات الفحص.
يُعد `--dangerously-force-unsafe-install` خيار كسر زجاج للطوارئ عند
النتائج الإيجابية الكاذبة في ماسح الشيفرة الخطرة المضمّن. فهو يسمح
للتثبيت بالمتابعة حتى عندما يبلغ الماسح المضمّن عن نتائج `critical`،
لكنه **لا** يتجاوز كتل سياسة الخطاف `before_install` الخاصة بالـ Plugin،
ولا يتجاوز أيضًا حالات فشل الفحص.
ينطبق هذا الخيار في CLI على تدفقات تثبيت/تحديث Plugin. أما تثبيتات تبعيات Skill
المدعومة بـ Gateway فتستخدم تجاوز الطلب المطابق `dangerouslyForceUnsafeInstall`,
بينما يبقى `openclaw skills install` تدفق تنزيل/تثبيت Skills منفصلًا من ClawHub.
تنطبق راية CLI هذه على تدفقات تثبيت/تحديث Plugin. أما تثبيتات تبعيات Skills
المدعومة من Gateway فتستخدم تجاوز الطلب المطابق `dangerouslyForceUnsafeInstall`،
بينما يظل `openclaw skills install` تدفق تنزيل/تثبيت Skills من ClawHub
منفصلًا.
يُعد `plugins install` أيضًا سطح التثبيت لحزم hook التي تعرض
`openclaw.hooks` في `package.json`. استخدم `openclaw hooks` لعرض hook
المفلتر وتمكين كل hook على حدة، وليس لتثبيت الحزمة.
يُعد `plugins install` أيضًا واجهة التثبيت لحِزم الخطافات التي تعرض
`openclaw.hooks` في `package.json`. استخدم `openclaw hooks` لعرض الخطافات
المصفّى وتمكين كل خطاف على حدة، وليس لتثبيت الحزمة.
مواصفات npm هي **للسجل فقط** (اسم الحزمة + **إصدار دقيق** اختياري أو
**dist-tag**). تُرفض مواصفات Git/URL/file ونطاقات semver. وتعمل تثبيتات
التبعيات باستخدام `--ignore-scripts` حفاظًا على الأمان.
تقتصر مواصفات npm على **السجل فقط** (اسم الحزمة مع **إصدار مطابق تمامًا** اختياري
أو **dist-tag**). ويتم رفض مواصفات Git/URL/file ونطاقات semver.
وتُشغَّل تثبيتات التبعيات باستخدام `--ignore-scripts` من أجل الأمان.
تبقى المواصفات المجردة و`@latest` على المسار المستقر. وإذا حلّ npm أيًا منهما
إلى إصدار prerelease، فسيتوقف OpenClaw ويطلب منك الاشتراك صراحةً عبر
وسم prerelease مثل `@beta`/`@rc` أو إصدار prerelease دقيق مثل
`@1.2.3-beta.4`.
تظل المواصفات المجردة و`@latest` على مسار الإصدارات المستقرة. وإذا قام npm بحل
أيٍّ منهما إلى إصدار prerelease، فإن OpenClaw يتوقف ويطلب منك الموافقة
الصريحة باستخدام وسم prerelease مثل `@beta`/`@rc` أو إصدار prerelease
مطابق مثل `@1.2.3-beta.4`.
إذا طابقت مواصفة تثبيت مجردة معرّف Plugin مضمّن (مثل `diffs`)، فسيقوم OpenClaw
بتثبيت Plugin المضمّن مباشرة. ولتثبيت حزمة npm بالاسم نفسه، استخدم مواصفة
محددة النطاق صريحة (مثل `@scope/diffs`).
إذا طابقت مواصفة تثبيت مجردة معرّف Plugin مضمّنًا (مثل `diffs`)، فسيقوم OpenClaw
بتثبيت Plugin المضمّن مباشرة. ولتثبيت حزمة npm بالاسم نفسه، استخدم
مواصفة ذات نطاق صريحة (مثل `@scope/diffs`).
الأرشيفات المدعومة: `.zip`, `.tgz`, `.tar.gz`, `.tar`.
الأرشيفات المدعومة: `.zip` و`.tgz` و`.tar.gz` و`.tar`.
تُدعم أيضًا تثبيتات Claude marketplace.
تُدعَم أيضًا تثبيتات Claude marketplace.
تستخدم تثبيتات ClawHub محددًا صريحًا من نوع `clawhub:<package>`:
تستخدم تثبيتات ClawHub محدِّدًا صريحًا بصيغة `clawhub:<package>`:
```bash
openclaw plugins install clawhub:openclaw-codex-app-server
openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3
```
يفضّل OpenClaw الآن أيضًا ClawHub لمواصفات Plugin المجردة الآمنة لـ npm. ولا
يعود إلى npm إلا إذا لم يكن ClawHub يملك تلك الحزمة أو ذلك الإصدار:
يفضّل OpenClaw الآن أيضًا ClawHub لمواصفات Plugin المجردة والآمنة المتوافقة مع npm.
ولا يعود إلى npm إلا إذا لم تكن تلك الحزمة أو ذلك الإصدار موجودًا في ClawHub:
```bash
openclaw plugins install openclaw-codex-app-server
```
يقوم OpenClaw بتنزيل أرشيف الحزمة من ClawHub، ويتحقق من توافق
Plugin API المُعلن / الحد الأدنى لتوافق gateway، ثم يثبتها عبر مسار
الأرشيف المعتاد. وتحتفظ التثبيتات المسجلة ببياناتها الوصفية الخاصة بمصدر ClawHub
يقوم OpenClaw بتنزيل أرشيف الحزمة من ClawHub، ويفحص توافق واجهة برمجة Plugin /
الحد الأدنى من توافق Gateway المعلن، ثم يثبتها عبر مسار
الأرشيف المعتاد. وتحتفظ التثبيتات المسجلة ببيانات مصدر ClawHub الوصفية
لأجل التحديثات اللاحقة.
استخدم الصيغة المختصرة `plugin@marketplace` عندما يكون اسم marketplace موجودًا
في cache السجل المحلي لـ Claude ضمن `~/.claude/plugins/known_marketplaces.json`:
في ذاكرة Claude المحلية للسجل ضمن `~/.claude/plugins/known_marketplaces.json`:
```bash
openclaw plugins marketplace list <marketplace-name>
openclaw plugins install <plugin-name>@<marketplace-name>
```
استخدم `--marketplace` عندما تريد تمرير مصدر marketplace صراحةً:
استخدم `--marketplace` عندما تريد تمرير مصدر marketplace بشكل صريح:
```bash
openclaw plugins install <plugin-name> --marketplace <marketplace-name>
@ -171,33 +171,35 @@ openclaw plugins install <plugin-name> --marketplace ./my-marketplace
يمكن أن تكون مصادر marketplace:
- اسم marketplace معروف لـ Claude من `~/.claude/plugins/known_marketplaces.json`
- اسم marketplace معروف لدى Claude من `~/.claude/plugins/known_marketplaces.json`
- جذر marketplace محلي أو مسار `marketplace.json`
- صيغة مختصرة لمستودع GitHub مثل `owner/repo`
- عنوان URL لمستودع GitHub مثل `https://github.com/owner/repo`
- عنوان URL لـ git
- URL لمستودع GitHub مثل `https://github.com/owner/repo`
- URL لـ git
بالنسبة إلى marketpaces البعيدة المحمّلة من GitHub أو git، يجب أن تبقى إدخالات Plugin
داخل مستودع marketplace المستنسخ. يقبل OpenClaw مصادر المسارات النسبية من
ذلك المستودع ويرفض HTTP(S)، والمسارات المطلقة، وgit، وGitHub، وسائر
مصادر Plugin غير المعتمدة على المسار من manifests البعيدة.
بالنسبة إلى marketplaces البعيدة المحمّلة من GitHub أو git، يجب أن تبقى
إدخالات Plugin داخل مستودع marketplace المستنسخ. يقبل OpenClaw
مصادر المسارات النسبية من ذلك المستودع ويرفض مصادر Plugins من نوع HTTP(S)،
والمسارات المطلقة، وgit، وGitHub، وغيرها من المصادر غير المعتمدة على المسارات
من البيانات الوصفية البعيدة.
بالنسبة إلى المسارات المحلية والأرشيفات، يكتشف OpenClaw تلقائيًا:
- Plugins OpenClaw الأصلية (`openclaw.plugin.json`)
- الحزم المتوافقة مع Codex (`.codex-plugin/plugin.json`)
- الحزم المتوافقة مع Claude (`.claude-plugin/plugin.json` أو تخطيط مكونات Claude
الافتراضي)
- الحزم المتوافقة مع Cursor (`.cursor-plugin/plugin.json`)
- الحِزم المتوافقة مع Codex (`.codex-plugin/plugin.json`)
- الحِزم المتوافقة مع Claude (`.claude-plugin/plugin.json` أو تخطيط
مكونات Claude الافتراضي)
- الحِزم المتوافقة مع Cursor (`.cursor-plugin/plugin.json`)
تُثبَّت الحزم المتوافقة في جذر Plugin المعتاد وتشارك في التدفق نفسه لـ
list/info/enable/disable. وحتى الآن، تُدعم Skills الحزمة، وClaude
command-skills، وقيم Claude الافتراضية في `settings.json`, وافتراضات Claude `.lsp.json` /
`lspServers` المعلنة في manifest، وCursor command-skills، وأدلة hook المتوافقة
مع Codex؛ أما قدرات الحزم المكتشفة الأخرى فتُعرض في diagnostics/info
لكنها ليست موصولة بعد بتنفيذ بيئة التشغيل.
تُثبَّت الحِزم المتوافقة داخل جذر Plugin المعتاد وتشارك في
التدفق نفسه الخاص بـ list/info/enable/disable. حاليًا، تُدعَم Skills الخاصة بالحِزم،
وcommand-skills الخاصة بـ Claude، وقيم Claude الافتراضية في `settings.json`،
وقيم Claude الافتراضية في `.lsp.json` /
و`lspServers` المعلنة في البيان، وcommand-skills الخاصة بـ Cursor،
وأدلة الخطافات المتوافقة مع Codex؛ أما قدرات الحِزم المكتشفة الأخرى
فتُعرض في التشخيصات/المعلومات لكنها غير موصولة بعد بتنفيذ وقت التشغيل.
### List
### العرض
```bash
openclaw plugins list
@ -206,10 +208,10 @@ openclaw plugins list --verbose
openclaw plugins list --json
```
استخدم `--enabled` لإظهار Plugins المحمّلة فقط. واستخدم `--verbose` للتحول من
عرض الجدول إلى أسطر تفاصيل لكل Plugin تتضمن بيانات المصدر/الأصل/الإصدار/التفعيل.
واستخدم `--json` للحصول على جرد قابل للقراءة الآلية بالإضافة إلى
diagnostics السجل.
استخدم `--enabled` لإظهار Plugins المحمّلة فقط. واستخدم `--verbose` للانتقال من
عرض الجدول إلى أسطر تفاصيل لكل Plugin مع بيانات المصدر/المنشأ/الإصدار/التفعيل.
واستخدم `--json` للحصول على جرد قابل للقراءة آليًا مع
تشخيصات السجل.
استخدم `--link` لتجنب نسخ دليل محلي (يضيف إلى `plugins.load.paths`):
@ -217,13 +219,13 @@ diagnostics السجل.
openclaw plugins install -l ./my-plugin
```
لا يُدعم `--force` مع `--link` لأن التثبيتات المرتبطة تعيد استخدام
لا يُدعَم `--force` مع `--link` لأن التثبيتات المرتبطة تعيد استخدام
مسار المصدر بدلًا من النسخ فوق هدف تثبيت مُدار.
استخدم `--pin` مع تثبيتات npm لحفظ المواصفة الدقيقة المحلولة (`name@version`) في
`plugins.installs` مع إبقاء السلوك الافتراضي غير مثبّت.
استخدم `--pin` في تثبيتات npm لحفظ المواصفة الدقيقة المحلولة (`name@version`) في
`plugins.installs` مع الإبقاء على السلوك الافتراضي غير المثبّت.
### Uninstall
### إلغاء التثبيت
```bash
openclaw plugins uninstall <id>
@ -231,17 +233,18 @@ openclaw plugins uninstall <id> --dry-run
openclaw plugins uninstall <id> --keep-files
```
يزيل `uninstall` سجلات Plugin من `plugins.entries` و`plugins.installs`,
ومن قائمة السماح لـ Plugin، ومن إدخالات `plugins.load.paths` المرتبطة عند الاقتضاء.
وبالنسبة إلى Plugins الذاكرة النشطة، تعود خانة الذاكرة إلى `memory-core`.
يقوم `uninstall` بإزالة سجلات Plugin من `plugins.entries` و`plugins.installs`،
وقائمة السماح الخاصة بالـ Plugin، وإدخالات `plugins.load.paths` المرتبطة
عند الاقتضاء. وبالنسبة إلى Plugins الخاصة بـ Active Memory، تُعاد فتحة الذاكرة إلى
`memory-core`.
افتراضيًا، يزيل إلغاء التثبيت أيضًا دليل تثبيت Plugin تحت جذر Plugin في state-dir
النشط. استخدم
`--keep-files` للاحتفاظ بالملفات على القرص.
افتراضيًا، يزيل إلغاء التثبيت أيضًا دليل تثبيت Plugin تحت
جذر Plugin الخاص بـ state-dir النشط. استخدم
`--keep-files` للإبقاء على الملفات على القرص.
يُدعم `--keep-config` بوصفه اسمًا مستعارًا مهملًا لـ `--keep-files`.
يُدعَم `--keep-config` كاسم مستعار مهمل لـ `--keep-files`.
### Update
### التحديث
```bash
openclaw plugins update <id-or-npm-spec>
@ -251,64 +254,65 @@ openclaw plugins update @openclaw/voice-call@beta
openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install
```
تنطبق التحديثات على التثبيتات المتتبعة في `plugins.installs` وتثبيتات حزم hook
المتتبعة في `hooks.internal.installs`.
تنطبق التحديثات على التثبيتات المتتبَّعة في `plugins.installs` وتثبيتات
حِزم الخطافات المتتبَّعة في `hooks.internal.installs`.
عندما تمرر معرّف Plugin، يعيد OpenClaw استخدام مواصفة التثبيت المسجلة لذلك
Plugin. وهذا يعني أن dist-tags المخزنة سابقًا مثل `@beta` والإصدارات الدقيقة
المثبّتة تستمر في الاستخدام في تشغيلات `update <id>` اللاحقة.
الـ Plugin. وهذا يعني أن dist-tags المخزنة سابقًا مثل `@beta` والإصدارات
المثبتة تمامًا تستمر في الاستخدام في عمليات `update <id>` اللاحقة.
وبالنسبة إلى تثبيتات npm، يمكنك أيضًا تمرير مواصفة حزمة npm صريحة مع dist-tag
أو إصدار دقيق. ويحل OpenClaw اسم تلك الحزمة مجددًا إلى سجل Plugin المتتبَّع،
ويحدّث Plugin المثبّت، ويسجّل مواصفة npm الجديدة لأجل التحديثات المستقبلية
المعتمدة على المعرّف.
بالنسبة إلى تثبيتات npm، يمكنك أيضًا تمرير مواصفة صريحة لحزمة npm مع dist-tag
أو إصدار مطابق. يحل OpenClaw اسم تلك الحزمة مرة أخرى إلى سجل Plugin المتتبَّع،
ويحدّث Plugin المثبت، ويسجل مواصفة npm الجديدة
لتحديثات المعرف المستقبلية.
كما أن تمرير اسم حزمة npm من دون إصدار أو وسم يعيد أيضًا الحل إلى
سجل Plugin المتتبَّع. استخدم هذا عندما يكون Plugin مثبتًا على إصدار دقيق
إن تمرير اسم حزمة npm من دون إصدار أو وسم يعيد أيضًا الحل إلى
سجل Plugin المتتبَّع. استخدم ذلك عندما يكون Plugin مثبتًا على إصدار محدد تمامًا
وتريد إعادته إلى خط الإصدار الافتراضي في السجل.
قبل تحديث npm مباشر، يتحقق OpenClaw من إصدار الحزمة المثبتة مقابل بيانات
سجل npm الوصفية. وإذا كان الإصدار المثبّت وهوية العنصر المسجلة
يطابقان بالفعل الهدف المحلول، فيُتجاوز التحديث من دون تنزيل أو إعادة تثبيت
أو إعادة كتابة `openclaw.json`.
قبل تحديث npm فعلي، يفحص OpenClaw إصدار الحزمة المثبتة مقابل بيانات
سجل npm الوصفية. وإذا كان الإصدار المثبت وهوية
المكوّن المسجلة يطابقان الهدف المحلول بالفعل، يتم تخطي التحديث من دون
تنزيل أو إعادة تثبيت أو إعادة كتابة `openclaw.json`.
عندما يكون هناك تجزئة سلامة مخزنة وتتغير تجزئة العنصر الذي جرى جلبه،
يتعامل OpenClaw مع ذلك على أنه انجراف في عنصر npm. ويقوم الأمر التفاعلي
`openclaw plugins update` بطباعة التجزئات المتوقعة والفعلية ويطلب
عندما تكون قيمة hash سلامة مخزنة موجودة ويتغير hash المكوّن الذي جرى جلبه،
يعامل OpenClaw ذلك على أنه انجراف في مكوّن npm. ويقوم أمر
`openclaw plugins update` التفاعلي بطباعة hash المتوقع والفعلي ويطلب
التأكيد قبل المتابعة. أما مساعدات التحديث غير التفاعلية فتفشل بشكل مغلق
ما لم يوفّر المستدعي سياسة متابعة صريحة.
ما لم يزوّد المستدعي بسياسة متابعة صريحة.
يتوفر `--dangerously-force-unsafe-install` أيضًا مع `plugins update` بوصفه
تجاوز كسر زجاج للحالات الإيجابية الخاطئة في فحص التعليمات البرمجية الخطرة المدمج أثناء
تحديثات Plugin. وما يزال لا يتجاوز كتل سياسة `before_install` الخاصة بـ Plugin
ولا منع فشل الفحص، كما أنه ينطبق على تحديثات Plugin فقط، وليس على تحديثات حزم hook.
يتوفر `--dangerously-force-unsafe-install` أيضًا في `plugins update` كـ
تجاوز طوارئ عند النتائج الإيجابية الكاذبة في فحص الشيفرة الخطرة المضمّن أثناء
تحديثات Plugins. ومع ذلك، فهو لا يتجاوز كتل سياسة `before_install` الخاصة بالـ Plugin
ولا حظر فشل الفحص، كما أنه ينطبق فقط على تحديثات Plugins،
وليس على تحديثات حِزم الخطافات.
### Inspect
### الفحص
```bash
openclaw plugins inspect <id>
openclaw plugins inspect <id> --json
```
تفحّص عميق لـ Plugin واحدة. يعرض الهوية، وحالة التحميل، والمصدر،
والقدرات المسجلة، وhooks، والأدوات، والأوامر، والخدمات، وأساليب gateway،
ومسارات HTTP، وأعلام السياسات، وdiagnostics، وبيانات التثبيت الوصفية، وقدرات الحزمة،
وأي دعم مكتشف لـ MCP أو LSP server.
فحص عميق لـ Plugin واحد. يعرض الهوية، وحالة التحميل، والمصدر،
والقدرات المسجلة، والخطافات، والأدوات، والأوامر، والخدمات، وطرق Gateway،
ومسارات HTTP، وأعلام السياسة، والتشخيصات، وبيانات التثبيت الوصفية، وقدرات الحزمة،
وأي دعم مكتشف لخوادم MCP أو LSP.
تُصنَّف كل Plugin بحسب ما تسجله فعليًا في بيئة التشغيل:
يُصنَّف كل Plugin بحسب ما يسجله فعليًا في وقت التشغيل:
- **plain-capability** — نوع قدرة واحد (مثل Plugin خاصة بمزوّد فقط)
- **plain-capability** — نوع قدرة واحد (مثل Plugin يقتصر على موفر فقط)
- **hybrid-capability** — أنواع قدرات متعددة (مثل النص + الكلام + الصور)
- **hook-only** — hooks فقط، من دون قدرات أو أسطح
- **hook-only** — خطافات فقط، من دون قدرات أو أسطح
- **non-capability** — أدوات/أوامر/خدمات لكن من دون قدرات
راجع [أشكال Plugin](/ar/plugins/architecture#plugin-shapes) للمزيد عن نموذج القدرات.
راجع [أشكال Plugin](/ar/plugins/architecture#plugin-shapes) لمزيد من المعلومات حول نموذج القدرات.
يُخرج الخيار `--json` تقريرًا قابلًا للقراءة آليًا مناسبًا للنصوص البرمجية
تُخرج الراية `--json` تقريرًا قابلًا للقراءة آليًا ومناسبًا للبرمجة النصية
والتدقيق.
يعرض `inspect --all` جدولًا على مستوى الأسطول يتضمن الشكل، وأنواع القدرات،
وإشعارات التوافق، وقدرات الحزمة، وأعمدة ملخص hook.
يعرض `inspect --all` جدولًا على مستوى كامل المجموعة يتضمن أعمدة للشكل، وأنواع القدرات،
وملاحظات التوافق، وقدرات الحزمة، وملخص الخطافات.
`info` هو اسم مستعار لـ `inspect`.
@ -318,13 +322,13 @@ openclaw plugins inspect <id> --json
openclaw plugins doctor
```
يبلغ `doctor` عن أخطاء تحميل Plugin، وdiagnostics البيان/الاكتشاف،
وإشعارات التوافق. وعندما يكون كل شيء سليمًا فإنه يطبع `No plugin issues
يعرض `doctor` أخطاء تحميل Plugin، وتشخيصات البيان/الاكتشاف،
وملاحظات التوافق. وعندما يكون كل شيء سليمًا يطبع `No plugin issues
detected.`
بالنسبة إلى إخفاقات شكل الوحدة مثل غياب الصادرات `register`/`activate`، أعد التشغيل
في حالات فشل شكل الوحدة مثل غياب صادرات `register`/`activate`، أعد التشغيل
مع `OPENCLAW_PLUGIN_LOAD_DEBUG=1` لتضمين ملخص مضغوط لشكل الصادرات في
إخراج diagnostics.
مخرجات التشخيص.
### Marketplace
@ -333,7 +337,7 @@ openclaw plugins marketplace list <source>
openclaw plugins marketplace list <source> --json
```
يقبل `marketplace list` مسار marketplace محليًا، أو مسار `marketplace.json`,
أو صيغة GitHub مختصرة مثل `owner/repo`, أو عنوان URL لمستودع GitHub، أو عنوان URL لـ git.
ويطبع `--json` تسمية المصدر المحلولة بالإضافة إلى بيان marketplace المحلَّل
يقبل marketplace list مسار marketplace محليًا، أو مسار `marketplace.json`،
أو صيغة مختصرة لـ GitHub مثل `owner/repo`، أو URL لمستودع GitHub، أو URL لـ git.
وتطبع `--json` تسمية المصدر المحلولة بالإضافة إلى بيان marketplace المحلَّل
وإدخالات Plugin.

49
docs/ar/cli/proxy.md Normal file
View File

@ -0,0 +1,49 @@
---
read_when:
- تحتاج إلى التقاط حركة نقل OpenClaw محليًا لأغراض التصحيح
- تريد فحص جلسات الوكيل الخاص بالتصحيح، أو الكائنات الثنائية الكبيرة، أو إعدادات الاستعلام المسبقة المدمجة
summary: مرجع CLI لـ `openclaw proxy`، والوكيل المحلي للتصحيح، ومفتش الالتقاط
title: وكيل
x-i18n:
generated_at: "2026-04-23T13:59:00Z"
model: gpt-5.4
provider: openai
source_hash: 274de676a558153be85e345917c67647eb7e755b01869bc29e1effba66a7e828
source_path: cli/proxy.md
workflow: 15
---
# `openclaw proxy`
شغّل وكيل التصحيح المحلي الصريح وافحص الحركة الملتقطة.
هذا أمر مخصص للتصحيح من أجل التحقيق على مستوى النقل. ويمكنه تشغيل وكيل محلي، وتشغيل أمر فرعي مع تفعيل الالتقاط، وسرد جلسات الالتقاط، والاستعلام عن أنماط الحركة الشائعة، وقراءة الكائنات الثنائية الكبيرة الملتقطة، وحذف بيانات الالتقاط المحلية.
## الأوامر
```bash
openclaw proxy start [--host <host>] [--port <port>]
openclaw proxy run [--host <host>] [--port <port>] -- <cmd...>
openclaw proxy coverage
openclaw proxy sessions [--limit <count>]
openclaw proxy query --preset <name> [--session <id>]
openclaw proxy blob --id <blobId>
openclaw proxy purge
```
## إعدادات الاستعلام المسبقة
يقبل `openclaw proxy query --preset <name>` ما يلي:
- `double-sends`
- `retry-storms`
- `cache-busting`
- `ws-duplicate-frames`
- `missing-ack`
- `error-bursts`
## ملاحظات
- يستخدم `start` القيمة الافتراضية `127.0.0.1` ما لم يتم تعيين `--host`.
- يبدأ `run` وكيل تصحيح محليًا ثم يشغّل الأمر الذي يلي `--`.
- اللقطات هي بيانات تصحيح محلية؛ استخدم `openclaw proxy purge` عند الانتهاء.

39
docs/ar/cli/status.md
View File

@ -1,14 +1,14 @@
---
read_when:
- أنت تريد تشخيصًا سريعًا لصحة القنوات + أحدث مستلمي الجلسة
- أنت تريد حالة “all” قابلة للنسخ واللصق لأغراض التصحيح
summary: مرجع CLI للأمر `openclaw status` ‏(التشخيصات، والفحوصات، ولقطات الاستخدام)
- تريد تشخيصًا سريعًا لصحة القنوات + أحدث مستلمي الجلسات
- تريد حالة "all" قابلة للصق لأغراض تصحيح الأخطاء
summary: مرجع CLI لـ `openclaw status` (التشخيصات، الفحوصات، ولقطات الاستخدام)
title: status
x-i18n:
generated_at: "2026-04-05T12:39:39Z"
generated_at: "2026-04-23T13:59:06Z"
model: gpt-5.4
provider: openai
source_hash: fbe9d94fbe9938cd946ee6f293b5bd3b464b75e1ade2eacdd851788c3bffe94e
source_hash: 015614e329ec172a62c625581897fa64589f12dfe28edefe8a2764b5b5367b2a
source_path: cli/status.md
workflow: 15
---
@ -26,17 +26,18 @@ openclaw status --usage
ملاحظات:
- يقوم `--deep` بتشغيل فحوصات مباشرة (WhatsApp Web + Telegram + Discord + Slack + Signal).
- يطبع `--usage` نوافذ استخدام المزوّدين المطبعّة على شكل `X% left`.
- تمثل حقول `usage_percent` / `usagePercent` الخام في MiniMax الحصة المتبقية، لذلك يعكسها OpenClaw قبل العرض؛ وتكون الأولوية للحقول المعتمدة على العد عند وجودها. وتفضّل استجابات `model_remains` إدخال نموذج الدردشة، وتستمد تسمية النافذة من الطوابع الزمنية عند الحاجة، وتضمّن اسم النموذج في تسمية الخطة.
- عندما تكون لقطة الجلسة الحالية متناثرة، يمكن لـ `/status` استكمال عدادات الرموز وcache من أحدث سجل استخدام في السجل النصي. وتظل القيم المباشرة غير الصفرية الموجودة لها الأولوية على قيم التراجع من السجل النصي.
- يمكن لتراجع السجل النصي أيضًا استعادة تسمية نموذج وقت التشغيل النشط عندما يكون إدخال الجلسة المباشر مفقودًا لها. وإذا اختلف نموذج السجل النصي هذا عن النموذج المحدد، فإن status يحل نافذة السياق مقابل نموذج وقت التشغيل المستعاد بدلًا من النموذج المحدد.
- بالنسبة إلى احتساب حجم prompt، يفضّل تراجع السجل النصي الإجمالي الأكبر الموجّه إلى prompt عندما تكون بيانات الجلسة الوصفية مفقودة أو أصغر، حتى لا تنهار عروض الرموز إلى `0` في جلسات المزوّدات المخصصة.
- يتضمن الخرج مخازن جلسات لكل وكيل عند إعداد عدة وكلاء.
- تتضمن النظرة العامة حالة تثبيت/تشغيل خدمة المضيف الخاصة بـ Gateway + العقدة عند توفرها.
- تتضمن النظرة العامة قناة التحديث + git SHA ‏(لنسخ checkout المصدرية).
- تظهر معلومات التحديث في النظرة العامة؛ وإذا كان هناك تحديث متاح، يطبع status تلميحًا لتشغيل `openclaw update` ‏(راجع [التحديث](/install/updating)).
- تقوم أسطح الحالة للقراءة فقط (`status` و`status --json` و`status --all`) بحل SecretRefs المدعومة لمسارات الإعدادات المستهدفة عندما يكون ذلك ممكنًا.
- إذا تم إعداد SecretRef مدعوم لقناة ما لكنه غير متاح في مسار الأمر الحالي، فإن status يبقى للقراءة فقط ويبلغ عن خرج متدهور بدلًا من التعطل. ويعرض الخرج البشري تحذيرات مثل “configured token unavailable in this command path”، ويتضمن خرج JSON الحقل `secretDiagnostics`.
- عندما ينجح حل SecretRef المحلي للأمر، يفضّل status اللقطة المحلولة ويمسح علامات القنوات المؤقتة الخاصة بـ “secret unavailable” من الخرج النهائي.
- يتضمن `status --all` صفًا عامًا للأسرار وقسمًا للتشخيصات يلخص secret diagnostics ‏(مقتطعًا لتسهيل القراءة) من دون إيقاف إنشاء التقرير.
- يشغّل `--deep` فحوصات مباشرة (WhatsApp Web + Telegram + Discord + Slack + Signal).
- يطبع `--usage` نوافذ استخدام الموفر المطبّعة بصيغة `X% left`.
- يفصل إخراج حالة الجلسة الآن بين `Runtime:` و`Runner:`. يشير `Runtime` إلى مسار التنفيذ وحالة Sandbox (`direct`، `docker/*`)، بينما يوضح `Runner` ما إذا كانت الجلسة تستخدم Pi مضمّنًا، أو موفرًا مدعومًا عبر CLI، أو خلفية ACP harness مثل `codex (acp/acpx)`.
- تمثل الحقول الخام `usage_percent` / `usagePercent` في MiniMax الحصة المتبقية، لذلك يعكسها OpenClaw قبل العرض؛ وتكون الحقول المعتمدة على العدّ هي المعتمدة عند وجودها. وتفضّل استجابات `model_remains` إدخال نموذج الدردشة، وتستخرج تسمية النافذة من الطوابع الزمنية عند الحاجة، وتضمّن اسم النموذج في تسمية الخطة.
- عندما تكون لقطة الجلسة الحالية متناثرة، يمكن لـ `/status` استكمال عدادات الرموز وذاكرة التخزين المؤقت من أحدث سجل استخدام في السجل النصي. وتظل القيم الحية غير الصفرية الموجودة بالفعل هي المعتمدة على قيم الاسترجاع من السجل النصي.
- يمكن أيضًا للاسترجاع من السجل النصي استعادة تسمية نموذج Runtime النشط عندما يفتقدها إدخال الجلسة الحي. وإذا اختلف نموذج السجل النصي هذا عن النموذج المحدد، فستحل الحالة نافذة السياق استنادًا إلى نموذج Runtime المستعاد بدلًا من النموذج المحدد.
- بالنسبة إلى احتساب حجم prompt، يفضّل الاسترجاع من السجل النصي الإجمالي الأكبر الموجّه إلى prompt عندما تكون بيانات تعريف الجلسة مفقودة أو أصغر، حتى لا تنخفض جلسات الموفرات المخصصة إلى عرض `0` للرموز.
- يتضمن الإخراج مخازن جلسات لكل وكيل عند تكوين عدة وكلاء.
- تتضمن النظرة العامة حالة التثبيت/وقت التشغيل لخدمة Gateway + مضيف Node عند توفرها.
- تتضمن النظرة العامة قناة التحديث + Git SHA (لنسخ المصدر).
- تظهر معلومات التحديث في النظرة العامة؛ وإذا كان هناك تحديث متاح، تطبع الحالة تلميحًا لتشغيل `openclaw update` (راجع [التحديث](/ar/install/updating)).
- تحاول واجهات الحالة للقراءة فقط (`status` و`status --json` و`status --all`) حل SecretRefs المدعومة لمسارات التكوين المستهدفة عندما يكون ذلك ممكنًا.
- إذا تم تكوين SecretRef مدعوم لقناة ما لكنه غير متاح في مسار الأمر الحالي، تظل الحالة للقراءة فقط وتبلّغ عن مخرجات متدهورة بدلًا من التعطل. وتعرض المخرجات البشرية تحذيرات مثل “configured token unavailable in this command path”، كما تتضمن مخرجات JSON الحقل `secretDiagnostics`.
- عندما ينجح حل SecretRef المحلي للأمر، تفضّل الحالة اللقطة المحلولة وتمسح علامات القناة المؤقتة الخاصة بـ “secret unavailable” من المخرجات النهائية.
- يتضمن `status --all` صفًا عامًا لـ Secrets وقسمًا للتشخيصات يلخص تشخيصات الأسرار (مقتطعًا لتسهيل القراءة) من دون إيقاف إنشاء التقرير.

788
docs/ar/concepts/active-memory.md
View File

File diff suppressed because it is too large Load Diff

285
docs/ar/concepts/qa-e2e-automation.md
View File

@ -2,36 +2,36 @@
read_when:
- توسيع qa-lab أو qa-channel
- إضافة سيناريوهات QA مدعومة من المستودع
- بناء أتمتة QA بدرجة واقعية أعلى حول لوحة معلومات Gateway
summary: شكل أتمتة QA الخاص لـ qa-lab وqa-channel والسيناريوهات المُهيأة مسبقًا وتقارير البروتوكول
- بناء أتمتة QA ذات واقعية أعلى حول لوحة تحكم Gateway
summary: شكل أتمتة QA الخاصة لـ qa-lab وqa-channel والسيناريوهات المُهيّأة مسبقًا وتقارير البروتوكول
title: أتمتة QA الشاملة من البداية إلى النهاية
x-i18n:
generated_at: "2026-04-20T07:29:35Z"
generated_at: "2026-04-23T13:59:22Z"
model: gpt-5.4
provider: openai
source_hash: 34245ce871356caeab0d9e0eeeaa9fb4e408920a4a97ad27567fa365d8db17c7
source_hash: a967a74d2e70b042e9443c5ec954902b820d2e5a22cbecd9be74af13b9085553
source_path: concepts/qa-e2e-automation.md
workflow: 15
---
# أتمتة QA الشاملة من البداية إلى النهاية
تهدف حزمة QA الخاصة إلى اختبار OpenClaw بطريقة أكثر واقعية وتشبه القنوات
أكثر مما يمكن أن يقدمه اختبار وحدة واحد.
تهدف حزمة QA الخاصة إلى اختبار OpenClaw بطريقة أكثر واقعية
ومشابهة للقنوات من مجرد اختبار وحدة واحد.
المكوّنات الحالية:
المكونات الحالية:
- `extensions/qa-channel`: قناة رسائل اصطناعية بأسطح DM والقناة والخيط
- `extensions/qa-channel`: قناة رسائل اصطناعية تحتوي على أسطح للرسائل المباشرة والقناة والخيط
والتفاعل والتحرير والحذف.
- `extensions/qa-lab`: واجهة مستخدم للتصحيح وناقل QA لمراقبة النص الحواري،
وحقن الرسائل الواردة، وتصدير تقرير Markdown.
- `qa/`: أصول تمهيدية مدعومة من المستودع لمهمة البدء وسيناريوهات QA
- `extensions/qa-lab`: واجهة مستخدم لتصحيح الأخطاء وناقل QA لمراقبة السجل النصي
وحقن الرسائل الواردة وتصدير تقرير Markdown.
- `qa/`: أصول تهيئة أولية مدعومة من المستودع لمهمة الانطلاق وخطوط QA
الأساسية.
تدفّق عمل مشغّل QA الحالي هو موقع QA بلوحتين:
تدفق عمل مشغّل QA الحالي هو موقع QA ذو لوحتين:
- اليسار: لوحة معلومات Gateway ‏(Control UI) مع الوكيل.
- اليمين: QA Lab، يعرض النص الحواري الشبيه بـ Slack وخطة السيناريو.
- اليسار: لوحة تحكم Gateway (Control UI) مع الوكيل.
- اليمين: QA Lab، ويعرض سجلًا نصيًا شبيهًا بـ Slack وخطة السيناريو.
شغّله باستخدام:
@ -39,12 +39,13 @@ x-i18n:
pnpm qa:lab:up
```
يقوم هذا ببناء موقع QA، وبدء مسار Gateway المدعوم بـ Docker، وإتاحة
صفحة QA Lab حيث يمكن لمشغّل أو لحلقة أتمتة أن يكلّف الوكيل بمهمة QA،
ويراقب سلوك القناة الحقيقي، ويسجّل ما نجح وما فشل وما بقي معطّلًا.
يقوم هذا ببناء موقع QA، وبدء مسار Gateway مدعوم بـ Docker، ويعرض
صفحة QA Lab حيث يمكن للمشغّل أو حلقة الأتمتة إعطاء الوكيل
مهمة QA، ومراقبة سلوك القناة الفعلي، وتسجيل ما نجح أو فشل أو
ظل محظورًا.
للحصول على تكرار أسرع على واجهة QA Lab من دون إعادة بناء صورة Docker في كل مرة،
ابدأ الحزمة باستخدام حزمة QA Lab مركّبة عبر bind mount:
للحصول على تكرار أسرع في واجهة QA Lab دون إعادة بناء صورة Docker في كل مرة،
ابدأ الحزمة باستخدام حزمة QA Lab مركبة عبر bind mount:
```bash
pnpm openclaw qa docker-build-image
@ -53,165 +54,164 @@ pnpm qa:lab:up:fast
pnpm qa:lab:watch
```
يبقي `qa:lab:up:fast` خدمات Docker على صورة مبنية مسبقًا ويستخدم bind mount
لـ `extensions/qa-lab/web/dist` داخل حاوية `qa-lab`. ويعيد `qa:lab:watch`
بناء تلك الحزمة عند التغيير، ويُعاد تحميل المتصفح تلقائيًا عندما تتغير
بصمة أصول QA Lab.
يبقي `qa:lab:up:fast` خدمات Docker على صورة مبنية مسبقًا ويركب
`extensions/qa-lab/web/dist` داخل حاوية `qa-lab` عبر bind mount. ويقوم `qa:lab:watch`
بإعادة بناء تلك الحزمة عند التغيير، وتُعاد تحميل الصفحة في المتصفح تلقائيًا عندما يتغير
تجزئة أصول QA Lab.
لتشغيل مسار اختبار Matrix واقعي النقل، شغّل:
لتشغيل مسار smoke حقيقي للنقل لـ Matrix، نفّذ:
```bash
pnpm openclaw qa matrix
```
يوفّر هذا المسار خادم Tuwunel منزليًا مؤقتًا داخل Docker، ويسجّل
مستخدمين مؤقتين للسائق وSUT والمراقب، وينشئ غرفة خاصة واحدة، ثم يشغّل
Plugin ‏Matrix الحقيقي داخل عملية فرعية QA لـ Gateway. ويحافظ مسار النقل
الحي على ضبط العملية الفرعية محصورًا ضمن النقل قيد الاختبار، لذلك يعمل
Matrix من دون `qa-channel` في ضبط العملية الفرعية. ويكتب عناصر التقرير
المنظمة وسجل stdout/stderr الموحّد في دليل إخراج Matrix QA المحدد.
ولالتقاط خرج البناء/المشغّل الخارجي `scripts/run-node.mjs` أيضًا، اضبط
`OPENCLAW_RUN_NODE_OUTPUT_LOG=<path>` إلى ملف سجل محلي في المستودع.
يقوم هذا المسار بتهيئة خادم Tuwunel منزلي مؤقت داخل Docker، وتسجيل
مستخدمين مؤقتين للسائق وSUT والمراقب، وإنشاء غرفة خاصة واحدة، ثم تشغيل
Plugin الحقيقي لـ Matrix داخل عملية فرعية لـ QA gateway. ويحافظ مسار النقل الحي
على تكوين العملية الفرعية محصورًا في النقل قيد الاختبار، لذلك يعمل Matrix من دون
`qa-channel` في تكوين العملية الفرعية. ويكتب عناصر التقرير المنظم
وسجل stdout/stderr الموحّد في دليل مخرجات Matrix QA المحدد. وللالتقاط
مخرجات البناء/التشغيل الخاصة بـ `scripts/run-node.mjs` الخارجية أيضًا، اضبط
`OPENCLAW_RUN_NODE_OUTPUT_LOG=<path>` إلى ملف سجل محلي داخل المستودع.
لتشغيل مسار اختبار Telegram واقعي النقل، شغّل:
لتشغيل مسار smoke حقيقي للنقل لـ Telegram، نفّذ:
```bash
pnpm openclaw qa telegram
```
يستهدف هذا المسار مجموعة Telegram خاصة حقيقية واحدة بدلًا من توفير
خادم مؤقت. وهو يتطلب `OPENCLAW_QA_TELEGRAM_GROUP_ID`،
يستهدف هذا المسار مجموعة Telegram خاصة حقيقية واحدة بدلًا من تهيئة خادم
مؤقت. ويتطلب `OPENCLAW_QA_TELEGRAM_GROUP_ID`،
و`OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN`، و
`OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`، بالإضافة إلى
روبوتين مختلفين داخل المجموعة الخاصة نفسها. يجب أن يمتلك روبوت SUT
اسم مستخدم على Telegram، وتعمل المراقبة من روبوت إلى روبوت بأفضل شكل
عندما يكون Bot-to-Bot Communication Mode مفعّلًا لكلا الروبوتين في
`@BotFather`.
ينهي الأمر التنفيذ برمز غير صفري عند فشل أي سيناريو. استخدم `--allow-failures`
عندما تريد العناصر الناتجة من دون رمز خروج فاشل.
`OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`، بالإضافة إلى روبوتين مختلفين في المجموعة
الخاصة نفسها. يجب أن يمتلك روبوت SUT اسم مستخدم في Telegram، وتعمل
المراقبة بين الروبوتات بأفضل شكل عندما يكون لدى كلا الروبوتين وضع
Bot-to-Bot Communication Mode مفعّلًا في `@BotFather`.
يخرج الأمر برمز غير صفري عند فشل أي سيناريو. استخدم `--allow-failures` عندما
تريد العناصر الناتجة دون رمز خروج فاشل.
يتضمن تقرير Telegram وملخصه RTT لكل رد من طلب إرسال رسالة السائق
إلى رد SUT المرصود، بدءًا من canary.
تتشارك مسارات النقل الحية الآن عقدًا أصغر واحدًا بدلًا من أن يخترع كل منها
تتشارك مسارات النقل الحي الآن عقدًا أصغر واحدًا بدلًا من أن يخترع كل مسار
شكل قائمة السيناريوهات الخاص به:
يبقى `qa-channel` مجموعة السلوكيات الاصطناعية الواسعة على مستوى المنتج،
وليس جزءًا من مصفوفة تغطية النقل الحي.
يبقى `qa-channel` مجموعة سلوك المنتج الاصطناعية الواسعة وليس جزءًا
من مصفوفة تغطية النقل الحي.
| المسار | Canary | بوابة الإشارة | حظر قائمة السماح | رد من المستوى الأعلى | استئناف بعد إعادة التشغيل | متابعة الخيط | عزل الخيط | مراقبة التفاعل | أمر المساعدة |
| ------ | ------ | -------------- | ----------------- | --------------------- | -------------------------- | ------------ | ---------- | --------------- | ------------ |
| Matrix | x | x | x | x | x | x | x | x | |
| Telegram | x | | | | | | | | x |
| المسار | Canary | بوابة الإشارات | حظر قائمة السماح | رد على المستوى الأعلى | الاستئناف بعد إعادة التشغيل | متابعة الخيط | عزل الخيط | مراقبة التفاعل | أمر المساعدة |
| -------- | ------ | -------------- | ---------------- | ---------------------- | --------------------------- | ------------ | ---------- | ---------------- | ------------ |
| Matrix | x | x | x | x | x | x | x | x | |
| Telegram | x | | | | | | | | x |
يبقي هذا `qa-channel` كمجموعة سلوكيات واسعة على مستوى المنتج بينما تتشارك
Matrix وTelegram ووسائل النقل الحية المستقبلية قائمة تحقق صريحة واحدة
لعقد النقل.
يبقي هذا `qa-channel` مجموعة سلوك المنتج الواسعة بينما تتشارك
Matrix وTelegram ووسائل النقل الحية المستقبلية قائمة فحص صريحة واحدة لعقد النقل.
لتشغيل مسار Linux VM مؤقت من دون إدخال Docker في مسار QA، شغّل:
لتشغيل مسار Linux VM مؤقت من دون إدخال Docker في مسار QA، نفّذ:
```bash
pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline
```
يُقلع هذا ضيف Multipass جديدًا، ويثبّت التبعيات، ويبني OpenClaw داخل
الضيف، ويشغّل `qa suite`، ثم ينسخ تقرير QA العادي والملخص إلى
`.artifacts/qa-e2e/...` على المضيف.
يقوم هذا بتشغيل ضيف Multipass جديد، وتثبيت التبعيات، وبناء OpenClaw
داخل الضيف، وتشغيل `qa suite`، ثم نسخ تقرير QA العادي والملخص
مرة أخرى إلى `.artifacts/qa-e2e/...` على المضيف.
ويعيد استخدام سلوك اختيار السيناريو نفسه الذي يستخدمه `qa suite` على المضيف.
تنفّذ عمليات suite على المضيف وMultipass عدة سيناريوهات محددة بالتوازي
مع عمّال Gateway معزولين افتراضيًا. يفترض `qa-channel` درجة تزامن
افتراضية قدرها 4، مع حد أعلى بعدد السيناريوهات المحددة. استخدم
`--concurrency <count>` لضبط عدد العمّال، أو `--concurrency 1`
للتنفيذ التسلسلي.
ينهي الأمر التنفيذ برمز غير صفري عند فشل أي سيناريو. استخدم `--allow-failures`
عندما تريد العناصر الناتجة من دون رمز خروج فاشل.
تُنفّذ عمليات suite على المضيف وMultipass عدة سيناريوهات محددة بالتوازي
مع عمّال Gateway معزولين افتراضيًا. يستخدم `qa-channel` افتراضيًا تزامنًا بمقدار 4،
مع حد أقصى بعدد السيناريوهات المحددة. استخدم `--concurrency <count>` لضبط
عدد العمال، أو `--concurrency 1` للتنفيذ التسلسلي.
يخرج الأمر برمز غير صفري عند فشل أي سيناريو. استخدم `--allow-failures` عندما
تريد العناصر الناتجة دون رمز خروج فاشل.
تقوم التشغيلات الحية بتمرير مدخلات مصادقة QA المدعومة والعملية للضيف:
مفاتيح المزوّدات المعتمدة على env، ومسار ضبط مزوّد QA الحي، و
`CODEX_HOME` عند وجوده. أبقِ `--output-dir` داخل جذر المستودع لكي يتمكن
الضيف من الكتابة عائدًا عبر مساحة العمل المركّبة.
مفاتيح الموفر المعتمدة على env، ومسار تكوين موفر QA الحي، و
`CODEX_HOME` عند وجوده. أبقِ `--output-dir` تحت جذر المستودع حتى يتمكن الضيف
من الكتابة مرة أخرى عبر مساحة العمل المركبة.
## البذور المدعومة من المستودع
## العناصر الأولية المدعومة من المستودع
توجد أصول البذور في `qa/`:
توجد أصول التهيئة الأولية في `qa/`:
- `qa/scenarios/index.md`
- `qa/scenarios/<theme>/*.md`
هذه الملفات موجودة عمدًا في git بحيث تكون خطة QA مرئية للبشر وللوكيل
على حد سواء.
وُضعت هذه عمدًا داخل git حتى تكون خطة QA مرئية لكل من البشر
والوكيل.
يجب أن يبقى `qa-lab` مشغّل Markdown عامًا. يجب أن يكون كل ملف Markdown
للسيناريو هو مصدر الحقيقة لتشغيل اختبار واحد، ويجب أن يعرّف:
يجب أن يظل `qa-lab` مشغّل Markdown عامًا. يجب أن يكون كل ملف Markdown لسيناريو
هو المصدر المرجعي لتشغيل اختبار واحد، ويجب أن يحدد:
- بيانات تعريف السيناريو
- بيانات تعريف اختيارية للفئة والقدرة والمسار والمخاطر
- مراجع الوثائق والكود
- مراجع الوثائق والشفرة
- متطلبات Plugin اختيارية
- تصحيح ضبط Gateway اختياري
- تصحيح تكوين Gateway اختياري
- `qa-flow` القابل للتنفيذ
يُسمح لسطح وقت التشغيل القابل لإعادة الاستخدام الذي يدعم `qa-flow` بأن
يبقى عامًا وعابرًا للوظائف. على سبيل المثال، يمكن لسيناريوهات Markdown أن
تجمع بين أدوات جهة النقل وأدوات جهة المتصفح التي تقود Control UI المضمّن
عبر وصلة Gateway ‏`browser.request` من دون إضافة مشغّل بحالة خاصة.
يُسمح لسطح وقت التشغيل القابل لإعادة الاستخدام الذي يدعم `qa-flow` بأن يظل عامًا
وعابرًا للجوانب. على سبيل المثال، يمكن لسيناريوهات Markdown الجمع بين
مساعدات جهة النقل ومساعدات جهة المتصفح التي تقود Control UI المضمّن عبر
واجهة Gateway `browser.request` من دون إضافة مشغّل حالة خاصة.
يجب تجميع ملفات السيناريو حسب قدرة المنتج بدلًا من مجلد شجرة المصدر.
أبقِ معرّفات السيناريوهات ثابتة عند نقل الملفات؛ استخدم `docsRefs` و`codeRefs`
لتتبّع التنفيذ.
أبقِ معرّفات السيناريو مستقرة عند نقل الملفات؛ واستخدم `docsRefs` و`codeRefs`
لتتبع التنفيذ.
يجب أن تبقى القائمة الأساسية واسعة بما يكفي لتغطية:
يجب أن تظل القائمة الأساسية واسعة بما يكفي لتغطية:
- محادثات DM والقناة
- الرسائل المباشرة ودردشة القناة
- سلوك الخيوط
- دورة حياة إجراءات الرسائل
- استدعاءات Cron
- استرجاع الذاكرة
- تبديل النموذج
- تمرير العمل إلى الوكيل الفرعي
- استدعاء الذاكرة
- تبديل النماذج
- التسليم إلى وكيل فرعي
- قراءة المستودع وقراءة الوثائق
- مهمة بناء صغيرة مثل Lobster Invaders
- مهمة بناء صغيرة واحدة مثل Lobster Invaders
## مسارات مزوّدات المحاكاة
## مسارات mock للموفرين
يحتوي `qa suite` على مسارين محليين لمزوّدات المحاكاة:
يحتوي `qa suite` على مسارين محليين لـ mock الموفرين:
- `mock-openai` هو محاكي OpenClaw الواعي بالسيناريو. ويظل مسار المحاكاة
الحتمي الافتراضي لـ QA المدعوم من المستودع وبوابات التكافؤ.
- يبدأ `aimock` خادم مزوّد مدعومًا بـ AIMock لتغطية البروتوكول والتجهيزات
والتسجيل/إعادة التشغيل والفوضى بشكل تجريبي. وهو إضافة ولا يستبدل
- `mock-openai` هو mock الواعي بالسيناريوهات الخاص بـ OpenClaw. ويبقى
مسار mock الحتمي الافتراضي لـ QA المدعوم من المستودع وبوابات التكافؤ.
- يبدأ `aimock` خادم موفر مدعومًا بـ AIMock لتغطية البروتوكول والتجهيزات
والتسجيل/إعادة التشغيل والفوضى التجريبية. وهو إضافة ولا يستبدل
مرسل السيناريوهات `mock-openai`.
يوجد تنفيذ مسار المزوّد تحت `extensions/qa-lab/src/providers/`.
ويمتلك كل مزوّد إعداداته الافتراضية، وبدء خادمه المحلي، وضبط نموذج Gateway،
واحتياجات تهيئة ملف تعريف المصادقة، وعلامات القدرات الحية/التمثيلية.
يجب أن يمر كود suite وGateway المشترك عبر سجل المزوّدات بدلًا من
التفرع بناءً على أسماء المزوّدات.
يوجد تنفيذ مسارات الموفرين تحت `extensions/qa-lab/src/providers/`.
ويمتلك كل موفر إعداداته الافتراضية، وبدء الخادم المحلي، وتكوين نموذج Gateway،
واحتياجات إعداد ملفات المصادقة، وأعلام القدرات الحية/mock. ويجب أن يمر
الكود المشترك الخاص بـ suite وGateway عبر سجل الموفّرين بدلًا من التفرع
بناءً على أسماء الموفّرين.
## مهايئات النقل
## محولات النقل
يمتلك `qa-lab` وصلة نقل عامة لسيناريوهات QA في Markdown.
`qa-channel` هو أول مهايئ على تلك الوصلة، لكن هدف التصميم أوسع:
يجب أن تتمكن القنوات المستقبلية الحقيقية أو الاصطناعية من الاندماج في
مشغّل suite نفسه بدلًا من إضافة مشغّل QA خاص بالنقل.
يمتلك `qa-lab` واجهة نقل عامة لسيناريوهات QA في Markdown.
يُعد `qa-channel` أول محول على تلك الواجهة، لكن الهدف التصميمي أوسع:
يجب أن تتصل القنوات الحقيقية أو الاصطناعية المستقبلية بمشغّل suite نفسه
بدلًا من إضافة مشغّل QA خاص بالنقل.
على مستوى البنية، يكون التقسيم كما يلي:
على مستوى البنية، يكون التقسيم كالتالي:
- يمتلك `qa-lab` تنفيذ السيناريو العام، وتزامن العمّال، وكتابة العناصر الناتجة، وإعداد التقارير.
- يمتلك مهايئ النقل ضبط Gateway، والجاهزية، ومراقبة الوارد والصادر، وإجراءات النقل، وحالة النقل المطبّعة.
- تحدد ملفات سيناريوهات Markdown ضمن `qa/scenarios/` تشغيل الاختبار؛ ويوفر `qa-lab` سطح وقت التشغيل القابل لإعادة الاستخدام الذي ينفذه.
- يمتلك `qa-lab` تنفيذ السيناريوهات العام، وتزامن العمال، وكتابة العناصر الناتجة، وإعداد التقارير.
- يمتلك محول النقل تكوين Gateway، والجاهزية، ومراقبة الوارد والصادر، وإجراءات النقل، وحالة النقل المطبّعة.
- تحدد ملفات سيناريو Markdown تحت `qa/scenarios/` تشغيل الاختبار؛ ويوفر `qa-lab` سطح وقت التشغيل القابل لإعادة الاستخدام الذي ينفذها.
توجد إرشادات التبنّي الخاصة بالمشرفين لمهايئات القنوات الجديدة في
[Testing](/ar/help/testing#adding-a-channel-to-qa).
توجد إرشادات الاعتماد الموجهة للمشرفين لمحولات القنوات الجديدة في
[الاختبار](/ar/help/testing#adding-a-channel-to-qa).
## إعداد التقارير
يصدّر `qa-lab` تقرير بروتوكول بصيغة Markdown من الخط الزمني للناقل المُراقب.
يصدر `qa-lab` تقرير بروتوكول Markdown من الخط الزمني للناقل المرصود.
يجب أن يجيب التقرير عن:
- ما الذي نجح
- ما الذي فشل
- ما الذي بقي معطّلًا
- ما الذي ظل محظورًا
- ما سيناريوهات المتابعة الجديرة بالإضافة
لفحوصات الطابع والأسلوب، شغّل السيناريو نفسه عبر عدة مراجع نماذج حية
واكتب تقرير Markdown مُحكّمًا:
واكتب تقرير Markdown محكّمًا:
```bash
pnpm openclaw qa character-eval \
@ -230,41 +230,40 @@ pnpm openclaw qa character-eval \
--judge-concurrency 16
```
يشغّل هذا الأمر عمليات QA Gateway فرعية محلية، وليس Docker. يجب أن تضبط
سيناريوهات تقييم الطابع الشخصية من خلال `SOUL.md`، ثم تشغّل أدوار مستخدم
اعتيادية مثل الدردشة ومساعدة مساحة العمل ومهام الملفات الصغيرة. يجب ألّا
يُبلَّغ النموذج المرشح بأنه قيد التقييم. يحافظ الأمر على كل نص حواري كامل،
ويسجل إحصاءات التشغيل الأساسية، ثم يطلب من نماذج التحكيم في الوضع السريع
مع تفكير `xhigh` ترتيب التشغيلات حسب الطبيعية والانطباع العام والفكاهة.
استخدم `--blind-judge-models` عند مقارنة المزوّدات: يظل موجّه التحكيم
يتلقى كل نص حواري وحالة تشغيل، لكن مراجع المرشحين تُستبدل بوسوم محايدة
مثل `candidate-01`؛ ويعيد التقرير ربط الترتيب بالمراجع الحقيقية بعد
التحليل.
تستخدم تشغيلات المرشحين افتراضيًا تفكير `high`، مع `xhigh` لنماذج OpenAI
التي تدعمه. يمكنك تجاوز مرشح محدد ضمنيًا باستخدام
`--model provider/model,thinking=<level>`. ولا يزال `--thinking <level>`
يضبط قيمة احتياطية عامة، كما يُحتفظ بالنموذج الأقدم
`--model-thinking <provider/model=level>` من أجل التوافق.
تستخدم مراجع مرشحي OpenAI الوضع السريع افتراضيًا بحيث تُستخدم المعالجة ذات
الأولوية عندما يدعمها المزوّد. أضف `,fast` أو `,no-fast` أو `,fast=false`
ضمنيًا عندما يحتاج مرشح أو حكم واحد إلى تجاوز. مرّر `--fast` فقط عندما تريد
فرض الوضع السريع على كل نموذج مرشح. تُسجَّل مدد المرشحين والحكّام في التقرير
من أجل تحليل المقارنة المعيارية، لكن موجّهات الحكّام تنص صراحة على عدم
الترتيب حسب السرعة.
يستخدم كل من تشغيلات النماذج المرشحة والحكّام درجة تزامن 16 افتراضيًا.
خفّض `--concurrency` أو `--judge-concurrency` عندما تجعل حدود المزوّد أو ضغط
Gateway المحلي التشغيل شديد الضجيج.
عند عدم تمرير أي `--model` مرشح، يستخدم تقييم الطابع افتراضيًا
يشغّل هذا الأمر عمليات فرعية محلية لـ QA gateway، وليس Docker. يجب أن تضبط
سيناريوهات تقييم الشخصية persona عبر `SOUL.md`، ثم تشغّل أدوار مستخدم
عادية مثل الدردشة، ومساعدة مساحة العمل، ومهام الملفات الصغيرة. يجب ألا
يُخبر النموذج المرشح بأنه قيد التقييم. يحافظ الأمر على كل
سجل نصي كامل، ويسجل إحصاءات التشغيل الأساسية، ثم يطلب من نماذج التحكيم في الوضع السريع مع
استدلال `xhigh` ترتيب التشغيلات حسب الطبيعية والطابع والفكاهة.
استخدم `--blind-judge-models` عند مقارنة الموفّرين: لا يزال prompt التحكيم يتلقى
كل سجل نصي وحالة تشغيل، لكن تُستبدل مراجع المرشحين بملصقات محايدة
مثل `candidate-01`؛ ويعيد التقرير ربط التصنيفات بالمراجع الحقيقية بعد التحليل.
تستخدم تشغيلات المرشحين افتراضيًا تفكير `high`، مع `xhigh` لنماذج OpenAI التي
تدعمه. تجاوز مرشحًا محددًا ضمن السطر باستخدام
`--model provider/model,thinking=<level>`. ولا يزال `--thinking <level>` يضبط
قيمة احتياطية عامة، كما أن الصيغة الأقدم `--model-thinking <provider/model=level>` لا تزال
محفوظة للتوافق.
تستخدم مراجع مرشحي OpenAI الوضع السريع افتراضيًا حتى تُستخدم المعالجة ذات الأولوية
عندما يدعم الموفر ذلك. أضف `,fast` أو `,no-fast` أو `,fast=false` ضمن السطر عندما
يحتاج مرشح واحد أو محكّم واحد إلى تجاوز. مرّر `--fast` فقط عندما تريد
فرض الوضع السريع لكل نموذج مرشح. تُسجل مدد المرشحين والمحكّمين في
التقرير لتحليل القياس المعياري، لكن prompts التحكيم تنص صراحةً على
عدم الترتيب حسب السرعة.
يستخدم كل من تشغيلات نماذج المرشحين والمحكّمين افتراضيًا تزامنًا قدره 16. خفّض
`--concurrency` أو `--judge-concurrency` عندما تجعل حدود الموفر أو ضغط Gateway المحلي
التشغيل شديد التشويش.
عند عدم تمرير أي مرشح `--model`، يستخدم تقييم الشخصية افتراضيًا
`openai/gpt-5.4` و`openai/gpt-5.2` و`openai/gpt-5` و`anthropic/claude-opus-4-6`،
و`anthropic/claude-sonnet-4-6`، و`zai/glm-5.1`،
و`anthropic/claude-sonnet-4-6` و`zai/glm-5.1`،
و`moonshot/kimi-k2.5`، و
`google/gemini-3.1-pro-preview` عندما لا يتم تمرير `--model`.
وعند عدم تمرير أي `--judge-model`، تكون القيم الافتراضية للحكّام:
`google/gemini-3.1-pro-preview` عند عدم تمرير `--model`.
وعند عدم تمرير `--judge-model`، تكون المحكّمات الافتراضية هي
`openai/gpt-5.4,thinking=xhigh,fast` و
`anthropic/claude-opus-4-6,thinking=high`.
## الوثائق ذات الصلة
## وثائق ذات صلة
- [Testing](/ar/help/testing)
- [QA Channel](/ar/channels/qa-channel)
- [Dashboard](/web/dashboard)
- [الاختبار](/ar/help/testing)
- [قناة QA](/ar/channels/qa-channel)
- [لوحة التحكم](/ar/web/dashboard)

513
docs/ar/gateway/configuration.md
View File

@ -1,40 +1,40 @@
---
read_when:
- إعداد OpenClaw للمرة الأولى
- البحث عن أنماط إعدادات شائعة
- الانتقال إلى أقسام إعدادات محددة
summary: 'نظرة عامة على الإعدادات: المهام الشائعة، والإعداد السريع، وروابط المرجع الكامل'
title: الإعدادات
- البحث عن أنماط التكوين الشائعة
- الانتقال إلى أقسام التكوين المحددة
summary: 'نظرة عامة على التكوين: المهام الشائعة، الإعداد السريع، وروابط إلى المرجع الكامل'
title: التكوين
x-i18n:
generated_at: "2026-04-23T07:24:31Z"
generated_at: "2026-04-23T13:59:24Z"
model: gpt-5.4
provider: openai
source_hash: 8130d29e9fbf5104d0a76f26b26186b6aab2b211030b8c8ba0d1131daf890993
source_hash: d76b40c25f98de791e0d8012b2bc5b80e3e38dde99bb9105539e800ddac3f362
source_path: gateway/configuration.md
workflow: 15
---
# الإعدادات
# التكوين
يقرأ OpenClaw إعدادات اختيارية بصيغة <Tooltip tip="تدعم JSON5 التعليقات والفواصل اللاحقة">**JSON5**</Tooltip> من `~/.openclaw/openclaw.json`.
يجب أن يكون مسار الإعدادات النشط ملفًا عاديًا. التخطيطات التي تستخدم
`openclaw.json` كرابط رمزي غير مدعومة لعمليات الكتابة التي يملكها OpenClaw؛ إذ قد تستبدل
الكتابة الذرية المسار بدلًا من الحفاظ على الرابط الرمزي. إذا كنت تحتفظ بالإعدادات خارج
دليل الحالة الافتراضي، فوجّه `OPENCLAW_CONFIG_PATH` مباشرة إلى الملف الحقيقي.
يقرأ OpenClaw تكوين **JSON5** اختياريًا من `~/.openclaw/openclaw.json` <Tooltip tip="يدعم JSON5 التعليقات والفواصل اللاحقة"></Tooltip>.
يجب أن يكون مسار التكوين النشط ملفًا عاديًا. التخطيطات التي تستخدم
`openclaw.json` المرتبط برمز symlink غير مدعومة لعمليات الكتابة التي يملكها OpenClaw؛
قد تستبدل الكتابة الذرية المسار بدلًا من الحفاظ على الرابط الرمزي. إذا كنت تحتفظ
بالتكوين خارج دليل الحالة الافتراضي، فوجّه `OPENCLAW_CONFIG_PATH` مباشرةً إلى الملف الحقيقي.
إذا كان الملف مفقودًا، يستخدم OpenClaw إعدادات افتراضية آمنة. من الأسباب الشائعة لإضافة ملف إعدادات:
إذا كان الملف مفقودًا، يستخدم OpenClaw إعدادات افتراضية آمنة. ومن الأسباب الشائعة لإضافة تكوين:
- توصيل القنوات والتحكم في من يمكنه مراسلة البوت
- ضبط النماذج، والأدوات، والعزل، أو الأتمتة (Cron، وHooks)
- ضبط الجلسات، والوسائط، والشبكات، أو واجهة المستخدم
- ضبط النماذج والأدوات والعزل والأتمتة (Cron والخطافات)
- ضبط الجلسات والوسائط والشبكات أو واجهة المستخدم
راجع [المرجع الكامل](/ar/gateway/configuration-reference) لكل حقل متاح.
<Tip>
**هل أنت جديد على الإعدادات؟** ابدأ بـ `openclaw onboard` للإعداد التفاعلي، أو اطّلع على دليل [أمثلة الإعدادات](/ar/gateway/configuration-examples) للحصول على إعدادات كاملة جاهزة للنسخ واللصق.
**هل أنت جديد على التكوين؟** ابدأ باستخدام `openclaw onboard` للإعداد التفاعلي، أو اطّلع على دليل [أمثلة التكوين](/ar/gateway/configuration-examples) للحصول على تكوينات كاملة جاهزة للنسخ واللصق.
</Tip>
## الحد الأدنى من الإعدادات
## الحد الأدنى من التكوين
```json5
// ~/.openclaw/openclaw.json
@ -44,105 +44,82 @@ x-i18n:
}
```
## تعديل الإعدادات
## تحرير التكوين
<Tabs>
<Tab title="المعالج التفاعلي">
```bash
openclaw onboard # تدفق الإعداد الأولي الكامل
openclaw configure # معالج الإعدادات
openclaw onboard # مسار الإعداد الكامل
openclaw configure # معالج التكوين
```
</Tab>
<Tab title="CLI (أوامر سطر واحد)">
<Tab title="CLI (أوامر مختصرة)">
```bash
openclaw config get agents.defaults.workspace
openclaw config set agents.defaults.heartbeat.every "2h"
openclaw config unset plugins.entries.brave.config.webSearch.apiKey
```
</Tab>
<Tab title="واجهة التحكم">
<Tab title="واجهة Control UI">
افتح [http://127.0.0.1:18789](http://127.0.0.1:18789) واستخدم علامة التبويب **Config**.
تعرض واجهة التحكم نموذجًا من مخطط الإعدادات الحي، بما في ذلك بيانات
التوثيق الوصفية للحقل `title` / `description` بالإضافة إلى مخططات Plugin والقنوات عند
توفرها، مع محرر **Raw JSON** كمسار هروب. وبالنسبة إلى
واجهات التعمق والأدوات الأخرى، يكشف gateway أيضًا `config.schema.lookup` من أجل
جلب عقدة مخطط واحدة محددة المسار مع ملخصات الأبناء المباشرين.
تعرض Control UI نموذجًا من مخطط التكوين المباشر، بما في ذلك بيانات التوثيق
الوصفية `title` / `description` بالإضافة إلى مخططات Plugin والقنوات عند
توفرها، مع محرر **Raw JSON** كخيار احتياطي. وبالنسبة إلى واجهات المستخدم
المتعمقة والأدوات الأخرى، يوفّر Gateway أيضًا `config.schema.lookup` من أجل
جلب عقدة مخطط واحدة ضمن نطاق مسار معيّن مع ملخصات الأبناء المباشرين.
</Tab>
<Tab title="تعديل مباشر">
عدّل `~/.openclaw/openclaw.json` مباشرةً. يراقب Gateway الملف ويطبق التغييرات تلقائيًا (راجع [إعادة التحميل السريع](#config-hot-reload)).
<Tab title="تحرير مباشر">
حرّر `~/.openclaw/openclaw.json` مباشرةً. يراقب Gateway الملف ويطبّق التغييرات تلقائيًا (راجع [إعادة التحميل الفوري](#config-hot-reload)).
</Tab>
</Tabs>
## التحقق الصارم
<Warning>
لا يقبل OpenClaw إلا الإعدادات التي تطابق المخطط بالكامل. أي مفاتيح غير معروفة، أو أنواع غير صحيحة، أو قيم غير صالحة ستجعل Gateway **يرفض البدء**. الاستثناء الوحيد على مستوى الجذر هو `$schema` ‏(سلسلة نصية)، حتى تتمكن المحررات من إرفاق بيانات JSON Schema الوصفية.
لا يقبل OpenClaw إلا التكوينات التي تطابق المخطط بالكامل. المفاتيح غير المعروفة، والأنواع المشوهة، أو القيم غير الصالحة تجعل Gateway **يرفض البدء**. الاستثناء الوحيد على مستوى الجذر هو `$schema` (سلسلة نصية)، حتى تتمكن المحررات من إرفاق بيانات JSON Schema الوصفية.
</Warning>
ملاحظات حول أدوات المخطط:
- يطبع `openclaw config schema` عائلة JSON Schema نفسها التي تستخدمها واجهة التحكم
والتحقق من الإعدادات.
- تعامل مع خرج هذا المخطط على أنه العقد القابل للقراءة آليًا المرجعي لملف
`openclaw.json`؛ وتقوم هذه النظرة العامة ومرجع الإعدادات بتلخيصه.
- تُنقل قيم `title` و`description` الخاصة بالحقول إلى خرج المخطط من أجل
أدوات المحرر والنماذج.
- ترث إدخالات الكائنات المتداخلة، وwildcard (`*`)، وعناصر المصفوفة (`[]`)
بيانات التوثيق الوصفية نفسها حيثما وُجد توثيق مطابق للحقول.
- ترث أيضًا فروع التركيبات `anyOf` / `oneOf` / `allOf` بيانات التوثيق
الوصفية نفسها، بحيث تحتفظ متغيرات union/intersection بمساعدة الحقول نفسها.
- يعيد `config.schema.lookup` مسار إعدادات واحدًا بعد التطبيع مع
عقدة مخطط سطحية (`title` و`description` و`type` و`enum` و`const` والحدود الشائعة
وحقول تحقق مشابهة)، وبيانات تلميح واجهة مستخدم وصفية مطابقة، وملخصات الأبناء
المباشرين لأدوات التعمق.
- يتم دمج مخططات Plugin/القنوات وقت التشغيل عندما يتمكن gateway من تحميل
سجل manifest الحالي.
- يكتشف `pnpm config:docs:check` الانجراف بين عناصر الأساس الخاصة بالإعدادات
المواجهة للتوثيق وسطح المخطط الحالي.
يطبع `openclaw config schema` مخطط JSON Schema القياسي المستخدم بواسطة Control UI
والتحقق. يجلب `config.schema.lookup` عقدة واحدة ضمن نطاق مسار معيّن مع
ملخصات الأبناء لأدوات الاستكشاف المتعمق. وتستمر بيانات التوثيق الوصفية
للحقلين `title`/`description` عبر الكائنات المتداخلة، والحرف البديل (`*`)،
وعناصر المصفوفات (`[]`)، وفروع `anyOf`/`oneOf`/`allOf`.
كما تُدمج مخططات Plugin والقنوات وقت التشغيل عند تحميل سجل manifest.
عند فشل التحقق:
- لا يتم إقلاع Gateway
- تعمل فقط أوامر التشخيص (`openclaw doctor` و`openclaw logs` و`openclaw health` و`openclaw status`)
- شغّل `openclaw doctor` لرؤية المشكلات الدقيقة
- لا يبدأ Gateway
- تعمل الأوامر التشخيصية فقط (`openclaw doctor`, `openclaw logs`, `openclaw health`, `openclaw status`)
- شغّل `openclaw doctor` لرؤية المشكلات بدقة
- شغّل `openclaw doctor --fix` (أو `--yes`) لتطبيق الإصلاحات
يحتفظ Gateway أيضًا بنسخة موثوقة من آخر إعدادات سليمة معروفة بعد نجاح بدء التشغيل. إذا
تم تعديل `openclaw.json` لاحقًا خارج OpenClaw ولم يعد صالحًا، فإن بدء التشغيل
وإعادة التحميل السريع يحافظان على الملف المعطوب كلقطة زمنية باسم `.clobbered.*`،
ويستعيدان نسخة آخر إعدادات سليمة معروفة، ويسجلان تحذيرًا واضحًا مع سبب الاستعادة.
كما تتعامل استعادة القراءة عند بدء التشغيل أيضًا مع الانخفاضات الحادة في الحجم، وغياب بيانات الإعدادات الوصفية، وغياب
`gateway.mode` على أنها مؤشرات تلف حرجة عندما كانت
نسخة آخر إعدادات سليمة معروفة تحتوي على تلك الحقول.
إذا تمت إضافة سطر حالة/سجل عن طريق الخطأ قبل إعداد JSON صالح
في غير ذلك، يمكن لبدء gateway و`openclaw doctor --fix` إزالة البادئة،
والاحتفاظ بالملف الملوث كملف `.clobbered.*`، ومتابعة العمل باستخدام
JSON المستعاد.
ويتلقى الدور التالي للوكيل الرئيسي أيضًا تحذيرًا كحدث نظام يخبره بأن
الإعدادات قد تم استعادتها ويجب عدم إعادة كتابتها بشكل أعمى. ويتم تحديث ترقية
آخر إعدادات سليمة معروفة بعد بدء تشغيل تم التحقق منه وبعد عمليات إعادة التحميل السريع المقبولة، بما في ذلك
عمليات كتابة الإعدادات التي يملكها OpenClaw عندما يظل تجزئة الملف المحفوظة مطابقة لعملية
الكتابة المقبولة. ويتم تخطي الترقية عندما يحتوي المرشح على
عناصر نائبة للأسرار منقّحة مثل `***` أو قيم رموز مميزة مختصرة.
يحتفظ Gateway بنسخة موثوقة أخيرة معروفة سليمة بعد كل بدء تشغيل ناجح.
إذا فشل `openclaw.json` لاحقًا في التحقق (أو أسقط `gateway.mode`، أو تقلص
بحدة، أو أُضيف إليه سطر سجل بالخطأ في البداية)، فإن OpenClaw يحتفظ بالملف
المعطوب باسم `.clobbered.*`، ويستعيد النسخة الأخيرة المعروفة السليمة، ويسجل
سبب الاستعادة. كما تتلقى دورة الوكيل التالية تحذيرًا كحدث نظام حتى لا يقوم
الوكيل الرئيسي بإعادة كتابة التكوين المستعاد بشكل أعمى. يتم تخطي الترقية إلى
النسخة الأخيرة المعروفة السليمة عندما يحتوي المرشح على عناصر نائبة لأسرار
محجوبة مثل `***`.
## المهام الشائعة
<AccordionGroup>
<Accordion title="إعداد قناة (WhatsApp أو Telegram أو Discord أو غيرها)">
لكل قناة قسم إعدادات خاص بها تحت `channels.<provider>`. راجع صفحة القناة المخصصة لخطوات الإعداد:
<Accordion title="إعداد قناة (WhatsApp أو Telegram أو Discord وما إلى ذلك)">
لكل قناة قسم تكوين خاص بها تحت `channels.<provider>`. راجع صفحة القناة المخصصة لخطوات الإعداد:
- [WhatsApp](/ar/channels/whatsapp) — ‏`channels.whatsapp`
- [Telegram](/ar/channels/telegram) — ‏`channels.telegram`
- [Discord](/ar/channels/discord) — ‏`channels.discord`
- [Feishu](/ar/channels/feishu) — ‏`channels.feishu`
- [Google Chat](/ar/channels/googlechat) — ‏`channels.googlechat`
- [Microsoft Teams](/ar/channels/msteams) — ‏`channels.msteams`
- [Slack](/ar/channels/slack) — ‏`channels.slack`
- [Signal](/ar/channels/signal) — ‏`channels.signal`
- [iMessage](/ar/channels/imessage) — ‏`channels.imessage`
- [Mattermost](/ar/channels/mattermost) — ‏`channels.mattermost`
- [WhatsApp](/ar/channels/whatsapp) — `channels.whatsapp`
- [Telegram](/ar/channels/telegram) — `channels.telegram`
- [Discord](/ar/channels/discord) — `channels.discord`
- [Feishu](/ar/channels/feishu) — `channels.feishu`
- [Google Chat](/ar/channels/googlechat) — `channels.googlechat`
- [Microsoft Teams](/ar/channels/msteams) — `channels.msteams`
- [Slack](/ar/channels/slack) — `channels.slack`
- [Signal](/ar/channels/signal) — `channels.signal`
- [iMessage](/ar/channels/imessage) — `channels.imessage`
- [Mattermost](/ar/channels/mattermost) — `channels.mattermost`
تشترك جميع القنوات في نمط سياسة الرسائل الخاصة نفسه:
تشترك جميع القنوات في نفس نمط سياسة الرسائل المباشرة:
```json5
{
@ -151,7 +128,7 @@ JSON المستعاد.
enabled: true,
botToken: "123:abc",
dmPolicy: "pairing", // pairing | allowlist | open | disabled
allowFrom: ["tg:123"], // فقط لـ allowlist/open
allowFrom: ["tg:123"], // only for allowlist/open
},
},
}
@ -159,8 +136,8 @@ JSON المستعاد.
</Accordion>
<Accordion title="اختيار النماذج وإعدادها">
اضبط النموذج الأساسي والبدائل الاختيارية:
<Accordion title="اختيار النماذج وتكوينها">
اضبط النموذج الأساسي وعمليات الرجوع الاختيارية:
```json5
{
@ -179,31 +156,31 @@ JSON المستعاد.
}
```
- يعرّف `agents.defaults.models` فهرس النماذج ويعمل كقائمة سماح للأمر `/model`.
- يعرّف `agents.defaults.models` فهرس النماذج ويعمل كقائمة السماح لأمر `/model`.
- استخدم `openclaw config set agents.defaults.models '<json>' --strict-json --merge` لإضافة إدخالات إلى قائمة السماح من دون إزالة النماذج الحالية. تُرفض عمليات الاستبدال العادية التي قد تزيل إدخالات ما لم تمرر `--replace`.
- تستخدم مراجع النماذج تنسيق `provider/model` ‏(مثل `anthropic/claude-opus-4-6`).
- يتحكم `agents.defaults.imageMaxDimensionPx` في تصغير أبعاد الصور في النص/الأداة (الافتراضي `1200`)؛ وعادةً ما تقلل القيم الأقل من استخدام رموز الرؤية في التشغيلات الثقيلة بلقطات الشاشة.
- راجع [CLI الخاص بالنماذج](/ar/concepts/models) لتبديل النماذج داخل الدردشة و[Model Failover](/ar/concepts/model-failover) لمعرفة سلوك تدوير المصادقة والبدائل.
- بالنسبة إلى المزوّدين المخصصين/المستضافين ذاتيًا، راجع [المزوّدون المخصصون](/ar/gateway/configuration-reference#custom-providers-and-base-urls) في المرجع.
- تستخدم مراجع النماذج التنسيق `provider/model` (مثل `anthropic/claude-opus-4-6`).
- يتحكم `agents.defaults.imageMaxDimensionPx` في تصغير صور النصوص وأدوات التشغيل (القيمة الافتراضية `1200`)؛ وعادةً ما تقلل القيم الأقل من استخدام vision-token في التشغيلات الكثيفة بلقطات الشاشة.
- راجع [Models CLI](/ar/concepts/models) لتبديل النماذج في المحادثة و[Model Failover](/ar/concepts/model-failover) لسلوك تدوير المصادقة والرجوع الاحتياطي.
- بالنسبة إلى موفري الخدمة المخصصين/ذاتيي الاستضافة، راجع [الموفرون المخصصون](/ar/gateway/configuration-reference#custom-providers-and-base-urls) في المرجع.
</Accordion>
<Accordion title="التحكم في من يمكنه مراسلة البوت">
يتم التحكم في الوصول إلى الرسائل الخاصة لكل قناة عبر `dmPolicy`:
يتم التحكم في الوصول إلى الرسائل المباشرة لكل قناة عبر `dmPolicy`:
- `"pairing"` (الافتراضي): يحصل المرسلون غير المعروفين على رمز اقتران لمرة واحدة للموافقة
- `"allowlist"`: المرسلون الموجودون فقط في `allowFrom` ‏(أو مخزن السماح الخاص بالاقتران)
- `"open"`: السماح لجميع الرسائل الخاصة الواردة (يتطلب `allowFrom: ["*"]`)
- `"disabled"`: تجاهل جميع الرسائل الخاصة
- `"pairing"` (افتراضي): يحصل المرسلون غير المعروفين على رمز اقتران لمرة واحدة للموافقة
- `"allowlist"`: يُسمح فقط للمرسلين الموجودين في `allowFrom` (أو مخزن السماح المقترن)
- `"open"`: السماح بجميع الرسائل المباشرة الواردة (يتطلب `allowFrom: ["*"]`)
- `"disabled"`: تجاهل جميع الرسائل المباشرة
بالنسبة إلى المجموعات، استخدم `groupPolicy` + `groupAllowFrom` أو قوائم السماح الخاصة بالقناة.
بالنسبة إلى المجموعات، استخدم `groupPolicy` + `groupAllowFrom` أو قوائم السماح الخاصة بالقنوات.
راجع [المرجع الكامل](/ar/gateway/configuration-reference#dm-and-group-access) للتفاصيل الخاصة بكل قناة.
راجع [المرجع الكامل](/ar/gateway/configuration-reference#dm-and-group-access) للحصول على التفاصيل الخاصة بكل قناة.
</Accordion>
<Accordion title="إعداد تقييد الإشارات في الدردشة الجماعية">
تفترض رسائل المجموعات افتراضيًا **اشتراط الإشارة**. قم بتكوين الأنماط لكل وكيل:
<Accordion title="إعداد التحكم بالإشارة في الدردشة الجماعية">
تكون الرسائل الجماعية افتراضيًا **تتطلب إشارة**. اضبط الأنماط لكل وكيل:
```json5
{
@ -225,15 +202,14 @@ JSON المستعاد.
}
```
- **إشارات البيانات الوصفية**: إشارات @ أصلية (WhatsApp tap-to-mention، وTelegram @bot، وما إلى ذلك)
- **الإشارات الوصفية**: إشارات @ الأصلية (الإشارة بالنقر في WhatsApp، أو Telegram @bot، وما إلى ذلك)
- **أنماط النص**: أنماط regex آمنة في `mentionPatterns`
- راجع [المرجع الكامل](/ar/gateway/configuration-reference#group-chat-mention-gating) لمعرفة التجاوزات الخاصة بكل قناة ووضع الدردشة الذاتية.
- راجع [المرجع الكامل](/ar/gateway/configuration-reference#group-chat-mention-gating) للحصول على التجاوزات الخاصة بكل قناة ووضع المحادثة الذاتية.
</Accordion>
<Accordion title="تقييد Skills لكل وكيل">
استخدم `agents.defaults.skills` كخط أساس مشترك، ثم تجاوز
الوكلاء المحددين باستخدام `agents.list[].skills`:
استخدم `agents.defaults.skills` كخط أساس مشترك، ثم تجاوز الوكلاء المحددين باستخدام `agents.list[].skills`:
```json5
{
@ -242,24 +218,24 @@ JSON المستعاد.
skills: ["github", "weather"],
},
list: [
{ id: "writer" }, // يرث github وweather
{ id: "docs", skills: ["docs-search"] }, // يستبدل الإعدادات الافتراضية
{ id: "locked-down", skills: [] }, // بدون Skills
{ id: "writer" }, // inherits github, weather
{ id: "docs", skills: ["docs-search"] }, // replaces defaults
{ id: "locked-down", skills: [] }, // no skills
],
},
}
```
- احذف `agents.defaults.skills` للحصول على Skills غير مقيّدة افتراضيًا.
- احذف `agents.list[].skills` لوراثة الإعدادات الافتراضية.
- احذف `agents.defaults.skills` لجعل Skills غير مقيّدة افتراضيًا.
- احذف `agents.list[].skills` لوراثة القيم الافتراضية.
- اضبط `agents.list[].skills: []` لعدم استخدام أي Skills.
- راجع [Skills](/ar/tools/skills) و[إعدادات Skills](/ar/tools/skills-config) و
[مرجع الإعدادات](/ar/gateway/configuration-reference#agents-defaults-skills).
- راجع [Skills](/ar/tools/skills) و[تكوين Skills](/ar/tools/skills-config) و
[مرجع التكوين](/ar/gateway/configuration-reference#agents-defaults-skills).
</Accordion>
<Accordion title="ضبط مراقبة سلامة قنوات gateway">
تحكم في مدى شدة إعادة تشغيل gateway للقنوات التي تبدو قديمة:
<Accordion title="ضبط مراقبة صحة القنوات في Gateway">
تحكم في مدى شدة قيام Gateway بإعادة تشغيل القنوات التي تبدو راكدة:
```json5
{
@ -281,20 +257,20 @@ JSON المستعاد.
}
```
- اضبط `gateway.channelHealthCheckMinutes: 0` لتعطيل عمليات إعادة التشغيل الخاصة بمراقبة السلامة على مستوى عام.
- يجب أن تكون `channelStaleEventThresholdMinutes` أكبر من أو تساوي فترة الفحص.
- استخدم `channels.<provider>.healthMonitor.enabled` أو `channels.<provider>.accounts.<id>.healthMonitor.enabled` لتعطيل إعادة التشغيل التلقائي لقناة أو حساب واحد من دون تعطيل المراقب العام.
- راجع [فحوصات السلامة](/ar/gateway/health) لتصحيح الأخطاء التشغيلية و[المرجع الكامل](/ar/gateway/configuration-reference#gateway) لجميع الحقول.
- اضبط `gateway.channelHealthCheckMinutes: 0` لتعطيل إعادة التشغيل الناتجة عن مراقبة الصحة على مستوى عالمي.
- يجب أن تكون `channelStaleEventThresholdMinutes` أكبر من أو مساوية لفاصل التحقق.
- استخدم `channels.<provider>.healthMonitor.enabled` أو `channels.<provider>.accounts.<id>.healthMonitor.enabled` لتعطيل إعادة التشغيل التلقائي لقناة أو حساب واحد من دون تعطيل المراقبة العامة.
- راجع [فحوصات الصحة](/ar/gateway/health) لتصحيح الأخطاء التشغيلية و[المرجع الكامل](/ar/gateway/configuration-reference#gateway) لجميع الحقول.
</Accordion>
<Accordion title="تكوين الجلسات وعمليات إعادة التعيين">
تتحكم الجلسات في استمرارية المحادثة وعزلها:
تتحكم الجلسات في استمرارية المحادثة والعزل:
```json5
{
session: {
dmScope: "per-channel-peer", // موصى به لعدة مستخدمين
dmScope: "per-channel-peer", // recommended for multi-user
threadBindings: {
enabled: true,
idleHours: 24,
@ -309,15 +285,15 @@ JSON المستعاد.
}
```
- `dmScope`: ‏`main` (مشترك) | `per-peer` | `per-channel-peer` | `per-account-channel-peer`
- `threadBindings`: الإعدادات الافتراضية العامة لتوجيه الجلسات المرتبطة بالسلاسل (يدعم Discord الأوامر `/focus` و`/unfocus` و`/agents` و`/session idle` و`/session max-age`).
- راجع [إدارة الجلسات](/ar/concepts/session) لمعرفة النطاق، وروابط الهوية، وسياسة الإرسال.
- `dmScope`: `main` (مشترك) | `per-peer` | `per-channel-peer` | `per-account-channel-peer`
- `threadBindings`: القيم الافتراضية العامة لتوجيه الجلسات المرتبطة بسلاسل الرسائل (يدعم Discord الأوامر `/focus` و`/unfocus` و`/agents` و`/session idle` و`/session max-age`).
- راجع [إدارة الجلسات](/ar/concepts/session) للنطاق وروابط الهوية وسياسة الإرسال.
- راجع [المرجع الكامل](/ar/gateway/configuration-reference#session) لجميع الحقول.
</Accordion>
<Accordion title="تمكين العزل">
شغّل جلسات الوكيل داخل بيئات تشغيل معزولة:
شغّل جلسات الوكيل في بيئات تشغيل معزولة:
```json5
{
@ -334,14 +310,14 @@ JSON المستعاد.
ابنِ الصورة أولًا: `scripts/sandbox-setup.sh`
راجع [العزل](/ar/gateway/sandboxing) للحصول على الدليل الكامل و[المرجع الكامل](/ar/gateway/configuration-reference#agentsdefaultssandbox) لجميع الخيارات.
راجع [العزل](/ar/gateway/sandboxing) للدليل الكامل و[المرجع الكامل](/ar/gateway/configuration-reference#agentsdefaultssandbox) لجميع الخيارات.
</Accordion>
<Accordion title="تمكين push المدعوم بالـ relay لإصدارات iOS الرسمية">
يتم تكوين push المدعوم بالـ relay في `openclaw.json`.
<Accordion title="تمكين الإشعارات الفورية المعتمدة على relay لبنيات iOS الرسمية">
يتم تكوين الإشعارات الفورية المعتمدة على relay في `openclaw.json`.
اضبط هذا في إعدادات gateway:
اضبط هذا في تكوين Gateway:
```json5
{
@ -365,37 +341,37 @@ JSON المستعاد.
openclaw config set gateway.push.apns.relay.baseUrl https://relay.example.com
```
ما الذي يفعله هذا:
ما يفعله هذا:
- يسمح للـ gateway بإرسال `push.test`، وإشعارات التنبيه للإيقاظ، وإيقاظات إعادة الاتصال عبر relay خارجي.
- يستخدم إذن إرسال محددًا بالتسجيل تُمرّره إلى الأمام تطبيقات iOS المقترنة. لا يحتاج gateway إلى رمز relay على مستوى النشر بالكامل.
- يربط كل تسجيل مدعوم بالـ relay بهوية gateway التي اقترن بها تطبيق iOS، بحيث لا يمكن لـ Gateway آخر إعادة استخدام التسجيل المخزن.
- يُبقي إصدارات iOS المحلية/اليدوية على APNs المباشر. تنطبق عمليات الإرسال المدعومة بالـ relay فقط على الإصدارات الرسمية الموزعة التي سُجلت عبر relay.
- يجب أن يطابق عنوان URL الأساسي للـ relay المضمّن في إصدار iOS الرسمي/TestFlight، حتى تصل حركة التسجيل والإرسال إلى نشر relay نفسه.
- يتيح لـ Gateway إرسال `push.test` وتنبيهات الإيقاظ وتنبيهات إعادة الاتصال عبر relay الخارجي.
- يستخدم منحة إرسال مرتبطة بالتسجيل يمررها تطبيق iOS المقترن. لا يحتاج Gateway إلى رمز relay على مستوى النشر كله.
- يربط كل تسجيل مدعوم بـ relay بهوية Gateway التي اقترن بها تطبيق iOS، بحيث لا يمكن لـ Gateway آخر إعادة استخدام التسجيل المخزن.
- يُبقي بنيات iOS المحلية/اليدوية على APNs المباشر. تنطبق عمليات الإرسال المدعومة بـ relay فقط على البنيات الرسمية الموزعة التي سجلت عبر relay.
- يجب أن يطابق عنوان URL الأساسي لـ relay المضمّن في بنية iOS الرسمية/TestFlight، حتى تصل حركة التسجيل والإرسال إلى نفس نشر relay.
التدفق من البداية إلى النهاية:
التدفق الكامل من طرف إلى طرف:
1. ثبّت إصدار iOS رسميًا/TestFlight تم تجميعه باستخدام عنوان URL الأساسي نفسه للـ relay.
2. اضبط `gateway.push.apns.relay.baseUrl` على الـ gateway.
3. اقترن تطبيق iOS مع الـ gateway ودَع كلًا من جلسات node وoperator تتصل.
4. يجلب تطبيق iOS هوية gateway، ويسجل لدى relay باستخدام App Attest مع إيصال التطبيق، ثم ينشر حمولة `push.apns.register` المدعومة بالـ relay إلى الـ gateway المقترن.
5. يخزن الـ gateway مقبض relay وإذن الإرسال، ثم يستخدمهما لـ `push.test`، وإشعارات الإيقاظ، وإيقاظات إعادة الاتصال.
1. ثبّت بنية iOS رسمية/TestFlight جرى تجميعها باستخدام عنوان URL الأساسي نفسه لـ relay.
2. اضبط `gateway.push.apns.relay.baseUrl` على Gateway.
3. اقترن تطبيق iOS مع Gateway ودع كلًا من جلسات Node والمشغّل تتصل.
4. يجلب تطبيق iOS هوية Gateway، ويسجل مع relay باستخدام App Attest مع إيصال التطبيق، ثم ينشر حمولة `push.apns.register` المدعومة بـ relay إلى Gateway المقترن.
5. يخزن Gateway معرّف relay ومنحة الإرسال، ثم يستخدمهما في `push.test` وتنبيهات الإيقاظ وتنبيهات إعادة الاتصال.
ملاحظات تشغيلية:
- إذا بدّلت تطبيق iOS إلى Gateway مختلف، فأعد توصيل التطبيق حتى يتمكن من نشر تسجيل relay جديد مرتبط بذلك الـ gateway.
- إذا أصدرت إصدار iOS جديدًا يشير إلى نشر relay مختلف، فسيقوم التطبيق بتحديث تسجيل relay المخزن مؤقتًا بدلًا من إعادة استخدام أصل relay القديم.
- إذا نقلت تطبيق iOS إلى Gateway مختلف، فأعد توصيل التطبيق حتى يتمكن من نشر تسجيل relay جديد مرتبط بذلك Gateway.
- إذا أصدرت بنية iOS جديدة تشير إلى نشر relay مختلف، فسيحدّث التطبيق تسجيل relay المخزن مؤقتًا بدلًا من إعادة استخدام أصل relay القديم.
ملاحظة التوافق:
- لا يزال كل من `OPENCLAW_APNS_RELAY_BASE_URL` و`OPENCLAW_APNS_RELAY_TIMEOUT_MS` يعملان كتجاوزات بيئة مؤقتة.
- يظل `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` مسار هروب تطويري خاصًا بـ loopback فقط؛ لا تحتفظ بعناوين URL للـ relay باستخدام HTTP في الإعدادات.
- لا يزال `OPENCLAW_APNS_RELAY_BASE_URL` و`OPENCLAW_APNS_RELAY_TIMEOUT_MS` يعملان كتجاوزات مؤقتة عبر متغيرات البيئة.
- يظل `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` مخرجًا تطويريًا يقتصر على local loopback؛ لا تحفظ عناوين URL لـ relay عبر HTTP في التكوين.
راجع [تطبيق iOS](/ar/platforms/ios#relay-backed-push-for-official-builds) للتدفق الكامل من البداية إلى النهاية و[تدفق المصادقة والثقة](/ar/platforms/ios#authentication-and-trust-flow) لنموذج أمان relay.
راجع [تطبيق iOS](/ar/platforms/ios#relay-backed-push-for-official-builds) للتدفق الكامل من طرف إلى طرف و[تدفق المصادقة والثقة](/ar/platforms/ios#authentication-and-trust-flow) لنموذج أمان relay.
</Accordion>
<Accordion title="إعداد Heartbeat ‏(عمليات تحقق دورية)">
<Accordion title="إعداد Heartbeat (عمليات تحقق دورية)">
```json5
{
agents: {
@ -409,10 +385,10 @@ JSON المستعاد.
}
```
- `every`: سلسلة مدة (`30m`، `2h`). اضبطها على `0m` للتعطيل.
- `target`: ‏`last` | `none` | `<channel-id>` (مثل `discord` أو `matrix` أو `telegram` أو `whatsapp`)
- `directPolicy`: ‏`allow` (الافتراضي) أو `block` لأهداف Heartbeat بنمط الرسائل الخاصة
- راجع [Heartbeat](/ar/gateway/heartbeat) للحصول على الدليل الكامل.
- `every`: سلسلة مدة (`30m`، `2h`). اضبط `0m` للتعطيل.
- `target`: `last` | `none` | `<channel-id>` (على سبيل المثال `discord` أو `matrix` أو `telegram` أو `whatsapp`)
- `directPolicy`: `allow` (افتراضي) أو `block` لأهداف Heartbeat بأسلوب الرسائل المباشرة
- راجع [Heartbeat](/ar/gateway/heartbeat) للدليل الكامل.
</Accordion>
@ -431,14 +407,14 @@ JSON المستعاد.
}
```
- `sessionRetention`: احذف جلسات التشغيل المعزولة المكتملة من `sessions.json` (الافتراضي `24h`؛ اضبطه على `false` للتعطيل).
- `runLog`: احذف `cron/runs/<jobId>.jsonl` بحسب الحجم والأسطر المحتفظ بها.
- `sessionRetention`: احذف جلسات التشغيل المعزولة المكتملة من `sessions.json` (الافتراضي `24h`؛ اضبط `false` للتعطيل).
- `runLog`: احذف `cron/runs/<jobId>.jsonl` حسب الحجم والأسطر المحتفظ بها.
- راجع [مهام Cron](/ar/automation/cron-jobs) للحصول على نظرة عامة على الميزة وأمثلة CLI.
</Accordion>
<Accordion title="إعداد Webhooks ‏(Hooks)">
فعّل نقاط نهاية HTTP Webhook على Gateway:
<Accordion title="إعداد Webhook (الخطافات)">
فعّل نقاط نهاية Webhook عبر HTTP على Gateway:
```json5
{
@ -461,20 +437,20 @@ JSON المستعاد.
}
```
ملاحظة أمان:
- تعامل مع جميع محتويات حمولة hook/webhook على أنها إدخال غير موثوق.
- استخدم `hooks.token` مخصصًا؛ ولا تعِد استخدام رمز Gateway المشترك.
- تكون مصادقة Hook عبر الترويسات فقط (`Authorization: Bearer ...` أو `x-openclaw-token`)؛ ويتم رفض رموز سلسلة الاستعلام.
- لا يمكن أن يكون `hooks.path` هو `/`؛ أبقِ إدخال webhook على مسار فرعي مخصص مثل `/hooks`.
- اترك أعلام تجاوز المحتوى غير الآمن معطلة (`hooks.gmail.allowUnsafeExternalContent` و`hooks.mappings[].allowUnsafeExternalContent`) ما لم تكن تنفذ تصحيح أخطاء محكم النطاق.
ملاحظة أمنية:
- تعامل مع كل محتوى حمولات hook/Webhook على أنه إدخال غير موثوق.
- استخدم `hooks.token` مخصصًا؛ لا تعِد استخدام الرمز المشترك لـ Gateway.
- مصادقة Hook تعتمد على الترويسة فقط (`Authorization: Bearer ...` أو `x-openclaw-token`)؛ تُرفض الرموز في سلسلة الاستعلام.
- لا يمكن أن تكون `hooks.path` مساوية لـ `/`؛ أبقِ دخول Webhook على مسار فرعي مخصص مثل `/hooks`.
- أبقِ علامات تجاوز المحتوى غير الآمن معطلة (`hooks.gmail.allowUnsafeExternalContent` و`hooks.mappings[].allowUnsafeExternalContent`) ما لم تكن تنفذ تصحيح أخطاء محدودًا بإحكام.
- إذا فعّلت `hooks.allowRequestSessionKey`، فاضبط أيضًا `hooks.allowedSessionKeyPrefixes` لتقييد مفاتيح الجلسة التي يختارها المتصل.
- بالنسبة إلى الوكلاء المدفوعين بواسطة hooks، فضّل طبقات نماذج حديثة قوية وسياسة أدوات صارمة (مثل المراسلة فقط مع العزل حيثما أمكن).
- بالنسبة إلى الوكلاء المعتمدين على hook، ففضّل مستويات نماذج حديثة قوية وسياسة أدوات صارمة (مثل المراسلة فقط مع العزل متى أمكن).
راجع [المرجع الكامل](/ar/gateway/configuration-reference#hooks) لجميع خيارات التعيين وتكامل Gmail.
</Accordion>
<Accordion title="تكوين توجيه متعدد الوكلاء">
<Accordion title="تكوين التوجيه متعدد الوكلاء">
شغّل عدة وكلاء معزولين بمساحات عمل وجلسات منفصلة:
```json5
@ -492,12 +468,12 @@ JSON المستعاد.
}
```
راجع [متعدد الوكلاء](/ar/concepts/multi-agent) و[المرجع الكامل](/ar/gateway/configuration-reference#multi-agent-routing) لقواعد الربط وملفات تعريف الوصول لكل وكيل.
راجع [الوكلاء المتعددون](/ar/concepts/multi-agent) و[المرجع الكامل](/ar/gateway/configuration-reference#multi-agent-routing) لقواعد الربط وملفات الوصول الخاصة بكل وكيل.
</Accordion>
<Accordion title="تقسيم الإعدادات إلى ملفات متعددة ($include)">
استخدم `$include` لتنظيم الإعدادات الكبيرة:
<Accordion title="تقسيم التكوين إلى ملفات متعددة ($include)">
استخدم `$include` لتنظيم التكوينات الكبيرة:
```json5
// ~/.openclaw/openclaw.json
@ -511,46 +487,47 @@ JSON المستعاد.
```
- **ملف واحد**: يستبدل الكائن الحاوي
- **مصفوفة ملفات**: يتم دمجها دمجًا عميقًا بالترتيب (اللاحق يفوز)
- **مفاتيح الأشقاء**: يتم دمجها بعد include ‏(وتتجاوز القيم المضمنة)
- **مصفوفة من الملفات**: تُدمج دمجًا عميقًا بالترتيب (الأخير يفوز)
- **المفاتيح الشقيقة**: تُدمج بعد التضمينات (وتتجاوز القيم المضمّنة)
- **تضمينات متداخلة**: مدعومة حتى عمق 10 مستويات
- **المسارات النسبية**: تُحل نسبةً إلى الملف الذي يتضمنها
- **عمليات الكتابة التي يملكها OpenClaw**: عندما يغيّر أحد عمليات الكتابة قسمًا علويًا واحدًا فقط
مدعومًا بتضمين ملف واحد مثل `plugins: { $include: "./plugins.json5" }`،
يقوم OpenClaw بتحديث الملف المضمّن ويترك `openclaw.json` كما هو
- **الكتابة العابرة غير المدعومة**: تفشل التضمينات الجذرية، ومصفوفات include، وعمليات التضمين
التي تحتوي على تجاوزات من الأشقاء بشكل مغلق بالنسبة إلى عمليات الكتابة التي يملكها OpenClaw بدلًا من
تسطيح الإعدادات
- **معالجة الأخطاء**: أخطاء واضحة للملفات المفقودة، وأخطاء التحليل، والتضمينات الدائرية
- **الكتابات التي يملكها OpenClaw**: عندما تغيّر الكتابة قسمًا واحدًا فقط من المستوى الأعلى
مدعومًا بتضمين ملف واحد مثل `plugins: { $include: "./plugins.json5" }`,
يحدّث OpenClaw ذلك الملف المضمّن ويترك `openclaw.json` دون تغيير
- **الكتابة العبرية غير المدعومة**: تفشل التضمينات الجذرية ومصفوفات التضمين والتضمينات
التي لها تجاوزات شقيقة بشكل مغلق في الكتابات التي يملكها OpenClaw بدلًا من
تسطيح التكوين
- **معالجة الأخطاء**: أخطاء واضحة للملفات المفقودة وأخطاء التحليل والتضمينات الدائرية
</Accordion>
</AccordionGroup>
## إعادة التحميل السريع للإعدادات
## إعادة التحميل الفوري للتكوين
يراقب Gateway الملف `~/.openclaw/openclaw.json` ويطبق التغييرات تلقائيًا — ولا حاجة إلى إعادة تشغيل يدوية لمعظم الإعدادات.
يراقب Gateway الملف `~/.openclaw/openclaw.json` ويطبق التغييرات تلقائيًا — لا حاجة إلى إعادة تشغيل يدوية لمعظم الإعدادات.
تُعامل التعديلات المباشرة على الملفات على أنها غير موثوقة إلى أن يتم التحقق منها. ينتظر المراقب
حتى يستقر اضطراب الكتابة/إعادة التسمية المؤقتة من المحرر، ثم يقرأ
الملف النهائي، ويرفض التعديلات الخارجية غير الصالحة باستعادة آخر إعدادات سليمة معروفة. تستخدم
عمليات كتابة الإعدادات التي يملكها OpenClaw البوابة نفسها الخاصة بالمخطط قبل الكتابة؛ وتُرفض عمليات الإفساد التدميرية مثل
إسقاط `gateway.mode` أو تقليص الملف بأكثر من النصف
تُعامل التعديلات المباشرة على الملف على أنها غير موثوقة حتى تجتاز التحقق. ينتظر
المراقب حتى تهدأ فوضى الكتابة المؤقتة/إعادة التسمية من المحرر، ثم يقرأ
الملف النهائي، ويرفض التعديلات الخارجية غير الصالحة عبر استعادة التكوين
الأخير المعروف السليم. تستخدم كتابات التكوين التي يملكها OpenClaw
بوابة المخطط نفسها قبل الكتابة؛ وتُرفض التخريبات الإتلافية مثل
إسقاط `gateway.mode` أو تقليص الملف لأكثر من النصف
وتُحفظ باسم `.rejected.*` للفحص.
إذا رأيت `Config auto-restored from last-known-good` أو
`config reload restored last-known-good config` في السجلات، فافحص ملف
`.clobbered.*` المطابق بجانب `openclaw.json`، وأصلح الحمولة المرفوضة، ثم شغّل
`.clobbered.*` المطابق بجوار `openclaw.json`، وأصلح الحمولة المرفوضة، ثم شغّل
`openclaw config validate`. راجع [استكشاف أخطاء Gateway وإصلاحها](/ar/gateway/troubleshooting#gateway-restored-last-known-good-config)
للحصول على قائمة التحقق الخاصة بالاستعادة.
للاطلاع على قائمة خطوات الاسترداد.
### أوضاع إعادة التحميل
| الوضع | السلوك |
| الوضع | السلوك |
| ---------------------- | --------------------------------------------------------------------------------------- |
| **`hybrid`** (الافتراضي) | يطبّق التغييرات الآمنة فورًا. ويعيد التشغيل تلقائيًا للتغييرات الحرجة. |
| **`hot`** | يطبّق التغييرات الآمنة فقط. ويسجل تحذيرًا عند الحاجة إلى إعادة تشغيل — وأنت تتولى ذلك. |
| **`restart`** | يعيد تشغيل Gateway عند أي تغيير في الإعدادات، سواء كان آمنًا أم لا. |
| **`off`** | يعطّل مراقبة الملفات. تصبح التغييرات فعالة عند إعادة التشغيل اليدوية التالية. |
| **`hybrid`** (افتراضي) | يطبق التغييرات الآمنة فورًا. ويعيد التشغيل تلقائيًا للتغييرات الحرجة. |
| **`hot`** | يطبق التغييرات الآمنة فقط. ويسجل تحذيرًا عند الحاجة إلى إعادة تشغيل — وتتولى أنت ذلك. |
| **`restart`** | يعيد تشغيل Gateway عند أي تغيير في التكوين، سواء كان آمنًا أم لا. |
| **`off`** | يعطّل مراقبة الملفات. تصبح التغييرات سارية عند إعادة التشغيل اليدوية التالية. |
```json5
{
@ -560,118 +537,74 @@ JSON المستعاد.
}
```
### ما الذي يُطبَّق سريعًا وما الذي يحتاج إلى إعادة تشغيل
### ما الذي يُطبَّق فورًا وما الذي يحتاج إلى إعادة تشغيل
تُطبَّق معظم الحقول سريعًا من دون توقف. وفي وضع `hybrid`، تتم معالجة التغييرات التي تتطلب إعادة تشغيل تلقائيًا.
تُطبَّق معظم الحقول فورًا من دون توقف للخدمة. وفي وضع `hybrid`، تُعالَج التغييرات التي تتطلب إعادة تشغيل تلقائيًا.
| الفئة | الحقول | هل يلزم إعادة تشغيل؟ |
| ------------------- | ----------------------------------------------------------------- | --------------- |
| القنوات | `channels.*`, `web` (WhatsApp) — جميع القنوات المضمنة وقنوات Plugin | لا |
| الوكيل والنماذج | `agent`, `agents`, `models`, `routing` | لا |
| الأتمتة | `hooks`, `cron`, `agent.heartbeat` | لا |
| الجلسات والرسائل | `session`, `messages` | لا |
| الأدوات والوسائط | `tools`, `browser`, `skills`, `audio`, `talk` | لا |
| واجهة المستخدم ومتفرقات | `ui`, `logging`, `identity`, `bindings` | لا |
| خادم Gateway | `gateway.*` (المنفذ، والربط، والمصادقة، وTailscale، وTLS، وHTTP) | **نعم** |
| البنية التحتية | `discovery`, `canvasHost`, `plugins` | **نعم** |
| الفئة | الحقول | هل يلزم إعادة تشغيل؟ |
| ------------------ | ----------------------------------------------------------------- | -------------------- |
| القنوات | `channels.*`, `web` (WhatsApp) — جميع القنوات المضمنة وقنوات Plugin | لا |
| الوكيل والنماذج | `agent`, `agents`, `models`, `routing` | لا |
| الأتمتة | `hooks`, `cron`, `agent.heartbeat` | لا |
| الجلسات والرسائل | `session`, `messages` | لا |
| الأدوات والوسائط | `tools`, `browser`, `skills`, `audio`, `talk` | لا |
| واجهة المستخدم ومتفرقات | `ui`, `logging`, `identity`, `bindings` | لا |
| خادم Gateway | `gateway.*` (المنفذ والربط والمصادقة وTailscale وTLS وHTTP) | **نعم** |
| البنية التحتية | `discovery`, `canvasHost`, `plugins` | **نعم** |
<Note>
يشكل كل من `gateway.reload` و`gateway.remote` استثناءين — فتغييرهما **لا** يؤدي إلى إعادة تشغيل.
`gateway.reload` و`gateway.remote` استثناءان — تغييرهما **لا** يؤدي إلى إعادة تشغيل.
</Note>
### تخطيط إعادة التحميل
عندما تعدّل ملف مصدر يُشار إليه عبر `$include`، يخطط OpenClaw
إعادة التحميل من التخطيط المؤلف في المصدر، وليس من العرض المسطح داخل الذاكرة.
ويبقي ذلك قرارات إعادة التحميل السريع (تطبيق سريع مقابل إعادة تشغيل) قابلة للتنبؤ حتى عندما
يكون قسم علوي واحد موجودًا في ملف مضمن مستقل مثل
`plugins: { $include: "./plugins.json5" }`.
عندما تحرر ملف مصدر يُشار إليه عبر `$include`، يخطط OpenClaw
إعادة التحميل من التخطيط المكتوب في المصدر، وليس من العرض المسطح داخل الذاكرة.
وهذا يجعل قرارات إعادة التحميل الفوري (تطبيق فوري أم إعادة تشغيل) قابلة للتنبؤ حتى عندما
يعيش قسم واحد من المستوى الأعلى في ملف مضمّن مستقل مثل
`plugins: { $include: "./plugins.json5" }`. يفشل تخطيط إعادة التحميل بشكل مغلق إذا كان
تخطيط المصدر ملتبسًا.
إذا تعذر تخطيط إعادة التحميل بأمان — على سبيل المثال، لأن تخطيط المصدر
يجمع بين تضمينات الجذر وتجاوزات الأشقاء — فإن OpenClaw يفشل بشكل مغلق، ويسجل
السبب، ويُبقي الإعدادات الحالية قيد التشغيل كما هي حتى تتمكن من إصلاح شكل
المصدر بدلًا من الرجوع بصمت إلى إعادة تحميل مسطّحة.
## Config RPC (تحديثات برمجية)
## Config RPC ‏(تحديثات برمجية)
بالنسبة إلى الأدوات التي تكتب التكوين عبر Gateway API، ففضّل هذا التدفق:
- `config.schema.lookup` لفحص شجرة فرعية واحدة (عقدة مخطط سطحية + ملخصات
الأبناء)
- `config.get` لجلب اللقطة الحالية مع `hash`
- `config.patch` للتحديثات الجزئية (JSON merge patch: الكائنات تُدمج، و`null`
يحذف، والمصفوفات تستبدل)
- `config.apply` فقط عندما تنوي استبدال التكوين بالكامل
- `update.run` لتنفيذ التحديث الذاتي الصريح مع إعادة التشغيل
<Note>
استدعاءات RPC الخاصة بكتابة مستوى التحكم (`config.apply`, `config.patch`, `update.run`) محدودة المعدل إلى **3 طلبات لكل 60 ثانية** لكل `deviceId+clientIp`. عند تطبيق الحد، يعيد RPC الرمز `UNAVAILABLE` مع `retryAfterMs`.
عمليات الكتابة على مستوى التحكم (`config.apply`, `config.patch`, `update.run`) تكون
محددة المعدل إلى 3 طلبات لكل 60 ثانية لكل `deviceId+clientIp`. وتُدمج طلبات إعادة
التشغيل ثم تفرض فترة تهدئة مدتها 30 ثانية بين دورات إعادة التشغيل.
</Note>
التدفق الآمن/الافتراضي:
مثال على patch جزئي:
- `config.schema.lookup`: افحص شجرة فرعية واحدة من الإعدادات محددة المسار مع
عقدة مخطط سطحية، وبيانات تلميح وصفية مطابقة، وملخصات الأبناء المباشرين
- `config.get`: اجلب اللقطة الحالية + التجزئة
- `config.patch`: المسار المفضل للتحديث الجزئي
- `config.apply`: استبدال الإعدادات بالكامل فقط
- `update.run`: تحديث ذاتي صريح + إعادة تشغيل
```bash
openclaw gateway call config.get --params '{}' # capture payload.hash
openclaw gateway call config.patch --params '{
"raw": "{ channels: { telegram: { groups: { \"*\": { requireMention: false } } } } }",
"baseHash": "<hash>"
}'
```
عندما لا تستبدل الإعدادات بالكامل، ففضّل `config.schema.lookup`
ثم `config.patch`.
<AccordionGroup>
<Accordion title="config.apply (استبدال كامل)">
يتحقق من الإعدادات الكاملة + يكتبها ويعيد تشغيل Gateway في خطوة واحدة.
<Warning>
يستبدل `config.apply` **الإعدادات بالكامل**. استخدم `config.patch` للتحديثات الجزئية، أو `openclaw config set` للمفاتيح المفردة.
</Warning>
المعاملات:
- `raw` (string) — حمولة JSON5 للإعدادات بالكامل
- `baseHash` (اختياري) — تجزئة الإعدادات من `config.get` (مطلوبة عند وجود إعدادات)
- `sessionKey` (اختياري) — مفتاح الجلسة لنبضة الإيقاظ بعد إعادة التشغيل
- `note` (اختياري) — ملاحظة لـ restart sentinel
- `restartDelayMs` (اختياري) — التأخير قبل إعادة التشغيل (الافتراضي 2000)
يتم دمج طلبات إعادة التشغيل عندما يكون أحدها معلقًا/قيد التنفيذ بالفعل، وتُطبّق فترة تهدئة مدتها 30 ثانية بين دورات إعادة التشغيل.
```bash
openclaw gateway call config.get --params '{}' # التقط payload.hash
openclaw gateway call config.apply --params '{
"raw": "{ agents: { defaults: { workspace: \"~/.openclaw/workspace\" } } }",
"baseHash": "<hash>",
"sessionKey": "agent:main:whatsapp:direct:+15555550123"
}'
```
</Accordion>
<Accordion title="config.patch (تحديث جزئي)">
يدمج تحديثًا جزئيًا في الإعدادات الموجودة (بدلالات JSON merge patch):
- يتم دمج الكائنات بشكل递归
- تحذف `null` مفتاحًا
- تستبدل المصفوفات بالكامل
المعاملات:
- `raw` (string) — JSON5 يحتوي فقط على المفاتيح المراد تغييرها
- `baseHash` (مطلوبة) — تجزئة الإعدادات من `config.get`
- `sessionKey` و`note` و`restartDelayMs` — مثل `config.apply`
يطابق سلوك إعادة التشغيل `config.apply`: عمليات إعادة تشغيل معلقة مدمجة بالإضافة إلى فترة تهدئة مدتها 30 ثانية بين دورات إعادة التشغيل.
```bash
openclaw gateway call config.patch --params '{
"raw": "{ channels: { telegram: { groups: { \"*\": { requireMention: false } } } } }",
"baseHash": "<hash>"
}'
```
</Accordion>
</AccordionGroup>
يقبل كل من `config.apply` و`config.patch` الحقول `raw` و`baseHash` و`sessionKey`,
`note` و`restartDelayMs`. يكون `baseHash` مطلوبًا للطريقتين عندما
يوجد تكوين بالفعل.
## متغيرات البيئة
يقرأ OpenClaw متغيرات البيئة من العملية الأب بالإضافة إلى:
يقرأ OpenClaw متغيرات البيئة من العملية الأم بالإضافة إلى:
- `.env` من دليل العمل الحالي (إن وجد)
- `~/.openclaw/.env` ‏(احتياطي عام)
- `.env` من دليل العمل الحالي (إذا وُجد)
- `~/.openclaw/.env` (بديل عام)
لا يتجاوز أي من الملفين متغيرات البيئة الموجودة بالفعل. يمكنك أيضًا ضبط متغيرات بيئة مضمّنة في الإعدادات:
لا يتجاوز أي من الملفين متغيرات البيئة الموجودة. ويمكنك أيضًا ضبط متغيرات بيئة مضمنة في التكوين:
```json5
{
@ -682,8 +615,8 @@ JSON المستعاد.
}
```
<Accordion title="استيراد env من shell (اختياري)">
إذا كان مفعّلًا ولم تكن المفاتيح المتوقعة مضبوطة، يشغّل OpenClaw shell تسجيل الدخول الخاص بك ويستورد فقط المفاتيح المفقودة:
<Accordion title="استيراد متغيرات بيئة Shell (اختياري)">
إذا كان مفعّلًا ولم تكن المفاتيح المتوقعة مضبوطة، يشغّل OpenClaw login shell الخاص بك ويستورد فقط المفاتيح المفقودة:
```json5
{
@ -696,8 +629,8 @@ JSON المستعاد.
المكافئ في متغيرات البيئة: `OPENCLAW_LOAD_SHELL_ENV=1`
</Accordion>
<Accordion title="استبدال متغيرات env في قيم الإعدادات">
ارجع إلى متغيرات env في أي قيمة سلسلة نصية ضمن الإعدادات باستخدام `${VAR_NAME}`:
<Accordion title="استبدال متغيرات البيئة في قيم التكوين">
أشر إلى متغيرات البيئة في أي قيمة سلسلة نصية في التكوين باستخدام `${VAR_NAME}`:
```json5
{
@ -710,13 +643,13 @@ JSON المستعاد.
- تتم مطابقة الأسماء المكتوبة بأحرف كبيرة فقط: `[A-Z_][A-Z0-9_]*`
- تؤدي المتغيرات المفقودة/الفارغة إلى خطأ وقت التحميل
- استخدم `$${VAR}` للخروج الحرفي
- يعمل ذلك داخل ملفات `$include`
- استخدم `$${VAR}` للهروب وإخراج القيمة حرفيًا
- يعمل داخل ملفات `$include`
- استبدال مضمن: `"${BASE}/v1"` → `"https://api.example.com/v1"`
</Accordion>
<Accordion title="مراجع الأسرار (env, file, exec)">
<Accordion title="مراجع الأسرار (env وfile وexec)">
بالنسبة إلى الحقول التي تدعم كائنات SecretRef، يمكنك استخدام:
```json5
@ -749,16 +682,16 @@ JSON المستعاد.
}
```
توجد تفاصيل SecretRef ‏(بما في ذلك `secrets.providers` لـ `env`/`file`/`exec`) في [إدارة الأسرار](/ar/gateway/secrets).
أما مسارات بيانات الاعتماد المدعومة فهي مدرجة في [سطح بيانات اعتماد SecretRef](/ar/reference/secretref-credential-surface).
توجد تفاصيل SecretRef (بما في ذلك `secrets.providers` الخاصة بـ `env`/`file`/`exec`) في [إدارة الأسرار](/ar/gateway/secrets).
وترد مسارات بيانات الاعتماد المدعومة في [واجهة بيانات اعتماد SecretRef](/ar/reference/secretref-credential-surface).
</Accordion>
راجع [البيئة](/ar/help/environment) لمعرفة الأولوية الكاملة والمصادر.
راجع [البيئة](/ar/help/environment) للحصول على الأولوية الكاملة والمصادر.
## المرجع الكامل
للحصول على المرجع الكامل حقلًا بحقل، راجع **[مرجع الإعدادات](/ar/gateway/configuration-reference)**.
للاطلاع على المرجع الكامل حقلًا بحقل، راجع **[مرجع التكوين](/ar/gateway/configuration-reference)**.
---
_ذو صلة: [أمثلة الإعدادات](/ar/gateway/configuration-examples) · [مرجع الإعدادات](/ar/gateway/configuration-reference) · [Doctor](/ar/gateway/doctor)_
_ذو صلة: [أمثلة التكوين](/ar/gateway/configuration-examples) · [مرجع التكوين](/ar/gateway/configuration-reference) · [Doctor](/ar/gateway/doctor)_

181
docs/ar/gateway/openshell.md
View File

@ -1,40 +1,40 @@
---
read_when:
- تريد صناديق حماية مُدارة سحابيًا بدلًا من Docker المحلي
- أنت تضبط Plugin الخاص بـ OpenShell
- تحتاج إلى الاختيار بين وضعي mirror وremote لمساحة العمل
summary: استخدام OpenShell كخلفية صندوق حماية مُدارة لوكلاء OpenClaw
- أنت تريد صناديق حماية مُدارة سحابيًا بدلًا من Docker المحلي
- أنت تقوم بإعداد Plugin ‏OpenShell
- تحتاج إلى الاختيار بين وضعي mirror وremote workspace
summary: استخدم OpenShell كواجهة خلفية لصندوق حماية مُدار لوكلاء OpenClaw
title: OpenShell
x-i18n:
generated_at: "2026-04-23T07:25:03Z"
generated_at: "2026-04-23T13:59:26Z"
model: gpt-5.4
provider: openai
source_hash: f93a8350fd48602bc535ec0480d0ed1665e558b37cc23c820ac90097862abd23
source_hash: 2534127b293364659a14df3e36583a9b7120f5d55cdbd8b4b611efe44adc7ff8
source_path: gateway/openshell.md
workflow: 15
---
# OpenShell
OpenShell هو خلفية صندوق حماية مُدارة لـ OpenClaw. وبدلًا من تشغيل حاويات Docker
محليًا، يفوّض OpenClaw دورة حياة صندوق الحماية إلى CLI الخاص بـ `openshell`،
يُعد OpenShell واجهة خلفية لصندوق حماية مُدار لـ OpenClaw. فبدلًا من تشغيل
حاويات Docker محليًا، يفوّض OpenClaw دورة حياة صندوق الحماية إلى CLI ‏`openshell`،
الذي يوفّر بيئات بعيدة مع تنفيذ أوامر قائم على SSH.
يعيد Plugin الخاص بـ OpenShell استخدام نقل SSH الأساسي نفسه وجسر
نظام الملفات البعيد الموجود في [خلفية SSH](/ar/gateway/sandboxing#ssh-backend) العامة. ويضيف
دورة حياة خاصة بـ OpenShell (`sandbox create/get/delete`, `sandbox ssh-config`)
يعيد Plugin ‏OpenShell استخدام نقل SSH الأساسي نفسه وجسر نظام الملفات البعيد
نفسه كما في [واجهة SSH الخلفية](/ar/gateway/sandboxing#ssh-backend) العامة. ويضيف
دورة حياة خاصة بـ OpenShell ‏(`sandbox create/get/delete`، و`sandbox ssh-config`)
ووضع مساحة عمل اختياريًا هو `mirror`.
## المتطلبات المسبقة
## المتطلبات الأساسية
- تثبيت CLI الخاص بـ `openshell` وتوفّره على `PATH` (أو ضبط مسار مخصص عبر
- تثبيت CLI ‏`openshell` ووجوده على `PATH` (أو تعيين مسار مخصص عبر
`plugins.entries.openshell.config.command`)
- حساب OpenShell مع صلاحية الوصول إلى صناديق الحماية
- حساب OpenShell مع إمكانية الوصول إلى sandbox
- تشغيل OpenClaw Gateway على المضيف
## البدء السريع
1. فعّل Plugin واضبط خلفية صندوق الحماية:
1. فعّل Plugin وعيّن الواجهة الخلفية لصندوق الحماية:
```json5
{
@ -62,8 +62,8 @@ OpenShell هو خلفية صندوق حماية مُدارة لـ OpenClaw. وب
}
```
2. أعد تشغيل Gateway. في الدورة التالية للوكيل، ينشئ OpenClaw
صندوق حماية OpenShell ويوجّه تنفيذ الأدوات من خلاله.
2. أعد تشغيل Gateway. في دورة الوكيل التالية، ينشئ OpenClaw
صندوق حماية OpenShell ويوجه تنفيذ الأدوات من خلاله.
3. تحقّق:
@ -78,84 +78,86 @@ openclaw sandbox explain
### `mirror`
استخدم `plugins.entries.openshell.config.mode: "mirror"` عندما تريد أن تبقى **مساحة العمل المحلية هي المرجع الأساسي**.
استخدم `plugins.entries.openshell.config.mode: "mirror"` عندما تريد أن **تبقى
مساحة العمل المحلية هي المرجع الأساسي**.
السلوك:
- قبل `exec`، يزامن OpenClaw مساحة العمل المحلية إلى صندوق حماية OpenShell.
- بعد `exec`، يزامن OpenClaw مساحة العمل البعيدة مرة أخرى إلى مساحة العمل المحلية.
- تظل أدوات الملفات تعمل من خلال جسر صندوق الحماية، لكن مساحة العمل المحلية
- تظل أدوات الملفات تعمل عبر جسر sandbox، لكن مساحة العمل المحلية
تبقى مصدر الحقيقة بين الدورات.
الأفضل لـ:
- إذا كنت تعدّل الملفات محليًا خارج OpenClaw وتريد أن تكون تلك التغييرات مرئية في
صندوق الحماية تلقائيًا.
- إذا كنت تريد أن يتصرف صندوق حماية OpenShell بأكبر قدر ممكن مثل خلفية Docker.
- إذا كنت تريد أن تعكس مساحة عمل المضيف عمليات الكتابة في صندوق الحماية بعد كل دورة exec.
- قيامك بتحرير الملفات محليًا خارج OpenClaw، وتريد أن تكون هذه التغييرات مرئية في
sandbox تلقائيًا.
- رغبتك في أن يتصرف صندوق حماية OpenShell بأكبر قدر ممكن مثل واجهة Docker الخلفية.
- رغبتك في أن تعكس مساحة عمل المضيف كتابات sandbox بعد كل دورة exec.
المقايضة: كلفة مزامنة إضافية قبل كل exec وبعده.
المقايضة: تكلفة مزامنة إضافية قبل كل exec وبعده.
### `remote`
استخدم `plugins.entries.openshell.config.mode: "remote"` عندما تريد أن تصبح **مساحة عمل OpenShell هي المرجع الأساسي**.
استخدم `plugins.entries.openshell.config.mode: "remote"` عندما تريد أن **تصبح
مساحة عمل OpenShell هي المرجع الأساسي**.
السلوك:
- عند إنشاء صندوق الحماية لأول مرة، يهيّئ OpenClaw مساحة العمل البعيدة انطلاقًا
- عند إنشاء صندوق الحماية للمرة الأولى، يهيّئ OpenClaw مساحة العمل البعيدة انطلاقًا
من مساحة العمل المحلية مرة واحدة.
- بعد ذلك، تعمل `exec` و`read` و`write` و`edit` و`apply_patch`
مباشرة على مساحة عمل OpenShell البعيدة.
مباشرةً على مساحة عمل OpenShell البعيدة.
- لا يقوم OpenClaw **بمزامنة** التغييرات البعيدة مرة أخرى إلى مساحة العمل المحلية.
- لا تزال قراءات الوسائط وقت المطالبة تعمل لأن أدوات الملفات والوسائط تقرأ عبر
جسر صندوق الحماية.
- تظل قراءات الوسائط وقت المطالبة تعمل لأن أدوات الملفات والوسائط تقرأ عبر
جسر sandbox.
الأفضل لـ:
- عندما يجب أن تعيش مساحة العمل أساسًا على الجانب البعيد.
- عندما تريد كلفة مزامنة أقل في كل دورة.
- عندما لا تريد أن تؤدي التعديلات المحلية على المضيف إلى الكتابة فوق حالة صندوق الحماية البعيد بصمت.
- أن تعيش sandbox أساسًا على الجانب البعيد.
- رغبتك في تقليل حمل المزامنة في كل دورة.
- عدم رغبتك في أن تؤدي تعديلات المضيف المحلية إلى الكتابة فوق حالة sandbox البعيدة بصمت.
مهم: إذا عدّلت ملفات على المضيف خارج OpenClaw بعد التهيئة الأولية،
فلن يرى صندوق الحماية البعيد تلك التغييرات. استخدم
مهم: إذا حرّرت ملفات على المضيف خارج OpenClaw بعد التهيئة الأولية،
فلن ترى sandbox البعيدة تلك التغييرات. استخدم
`openclaw sandbox recreate` لإعادة التهيئة.
### اختيار وضع
| | `mirror` | `remote` |
| ------------------------ | -------------------------- | ------------------------- |
| **مساحة العمل المرجعية** | المضيف المحلي | OpenShell البعيد |
| **اتجاه المزامنة** | ثنائي الاتجاه (كل exec) | تهيئة لمرة واحدة |
| **الكلفة في كل دورة** | أعلى (رفع + تنزيل) | أقل (عمليات بعيدة مباشرة) |
| **هل تظهر التعديلات المحلية؟** | نعم، في exec التالي | لا، حتى recreate |
| **الأفضل لـ** | تدفقات التطوير | الوكلاء طويلو التشغيل، وCI |
| | `mirror` | `remote` |
| ------------------------ | -------------------------- | --------------------------- |
| **مساحة العمل المرجعية** | المضيف المحلي | OpenShell البعيد |
| **اتجاه المزامنة** | ثنائي الاتجاه (كل exec) | تهيئة لمرة واحدة |
| **الحمل في كل دورة** | أعلى (رفع + تنزيل) | أقل (عمليات بعيدة مباشرة) |
| **هل تظهر التعديلات المحلية؟** | نعم، في exec التالية | لا، حتى recreate |
| **الأفضل لـ** | مهام سير عمل التطوير | الوكلاء طويلة التشغيل، وCI |
## مرجع الإعدادات
## مرجع الإعداد
توجد كل إعدادات OpenShell تحت `plugins.entries.openshell.config`:
توجد كل إعدادات OpenShell ضمن `plugins.entries.openshell.config`:
| المفتاح | النوع | الافتراضي | الوصف |
| ------------------------ | ------------------------ | ------------- | ----- |
| `mode` | `"mirror"` أو `"remote"` | `"mirror"` | وضع مزامنة مساحة العمل |
| `command` | `string` | `"openshell"` | مسار أو اسم CLI الخاص بـ `openshell` |
| `from` | `string` | `"openclaw"` | مصدر صندوق الحماية لأول إنشاء |
| `gateway` | `string` | — | اسم Gateway الخاص بـ OpenShell (`--gateway`) |
| `gatewayEndpoint` | `string` | — | عنوان URL لنقطة نهاية Gateway الخاصة بـ OpenShell (`--gateway-endpoint`) |
| `policy` | `string` | — | معرّف policy الخاص بـ OpenShell لإنشاء صندوق الحماية |
| `providers` | `string[]` | `[]` | أسماء المزوّدين المراد إرفاقهم عند إنشاء صندوق الحماية |
| `gpu` | `boolean` | `false` | طلب موارد GPU |
| `autoProviders` | `boolean` | `true` | تمرير `--auto-providers` أثناء إنشاء صندوق الحماية |
| `remoteWorkspaceDir` | `string` | `"/sandbox"` | مساحة العمل القابلة للكتابة الأساسية داخل صندوق الحماية |
| `remoteAgentWorkspaceDir`| `string` | `"/agent"` | مسار ربط مساحة عمل الوكيل (للوصول للقراءة فقط) |
| `timeoutSeconds` | `number` | `120` | المهلة الزمنية لعمليات CLI الخاصة بـ `openshell` |
| Key | Type | Default | الوصف |
| ------------------------- | ------------------------ | ------------- | ---------------------------------------------------- |
| `mode` | `"mirror"` أو `"remote"` | `"mirror"` | وضع مزامنة مساحة العمل |
| `command` | `string` | `"openshell"` | مسار أو اسم CLI ‏`openshell` |
| `from` | `string` | `"openclaw"` | مصدر sandbox عند الإنشاء لأول مرة |
| `gateway` | `string` | — | اسم OpenShell Gateway ‏(`--gateway`) |
| `gatewayEndpoint` | `string` | — | عنوان نقطة نهاية OpenShell Gateway ‏(`--gateway-endpoint`) |
| `policy` | `string` | — | معرّف سياسة OpenShell لإنشاء sandbox |
| `providers` | `string[]` | `[]` | أسماء الموفّرين المطلوب إرفاقها عند إنشاء sandbox |
| `gpu` | `boolean` | `false` | طلب موارد GPU |
| `autoProviders` | `boolean` | `true` | تمرير `--auto-providers` أثناء إنشاء sandbox |
| `remoteWorkspaceDir` | `string` | `"/sandbox"` | مساحة العمل الأساسية القابلة للكتابة داخل sandbox |
| `remoteAgentWorkspaceDir` | `string` | `"/agent"` | مسار تحميل مساحة عمل الوكيل (للوصول للقراءة فقط) |
| `timeoutSeconds` | `number` | `120` | مهلة عمليات CLI ‏`openshell` |
تُضبط الإعدادات على مستوى صندوق الحماية (`mode` و`scope` و`workspaceAccess`) تحت
`agents.defaults.sandbox` كما هو الحال مع أي خلفية. راجع
تُضبط إعدادات مستوى sandbox ‏(`mode` و`scope` و`workspaceAccess`) ضمن
`agents.defaults.sandbox` كما هو الحال مع أي واجهة خلفية. راجع
[Sandboxing](/ar/gateway/sandboxing) للاطلاع على المصفوفة الكاملة.
## أمثلة
### إعداد remote أدنى
### إعداد remote بسيط
```json5
{
@ -251,7 +253,7 @@ openclaw sandbox explain
## إدارة دورة الحياة
تُدار صناديق حماية OpenShell من خلال CLI العادي لصندوق الحماية:
تُدار صناديق حماية OpenShell عبر CLI المعتاد لصندوق الحماية:
```bash
# List all sandbox runtimes (Docker + OpenShell)
@ -264,16 +266,16 @@ openclaw sandbox explain
openclaw sandbox recreate --all
```
بالنسبة إلى وضع `remote`، تكون **إعادة الإنشاء مهمة بشكل خاص**: فهي تحذف
مساحة العمل البعيدة المرجعية لذلك النطاق. ويؤدي الاستخدام التالي إلى تهيئة
مساحة عمل بعيدة جديدة انطلاقًا من مساحة العمل المحلية.
في وضع `remote`، تكون **إعادة الإنشاء مهمة بشكل خاص**: فهي تحذف
مساحة العمل البعيدة المرجعية لذلك النطاق. وعند الاستخدام التالي تُهيَّأ مساحة عمل بعيدة جديدة
من مساحة العمل المحلية.
وبالنسبة إلى وضع `mirror`، فإن إعادة الإنشاء تعيد أساسًا ضبط بيئة التنفيذ البعيدة لأن
مساحة العمل المحلية تظل هي المرجع الأساسي.
أما في وضع `mirror`، فتعيد إعادة الإنشاء أساسًا ضبط بيئة التنفيذ البعيدة لأن
مساحة العمل المحلية تبقى هي المرجع الأساسي.
### متى تستخدم recreate
### متى يجب إعادة الإنشاء
استخدم recreate بعد تغيير أي من هذه القيم:
أعِد الإنشاء بعد تغيير أي مما يلي:
- `agents.defaults.sandbox.backend`
- `plugins.entries.openshell.config.from`
@ -284,43 +286,34 @@ openclaw sandbox recreate --all
openclaw sandbox recreate --all
```
## تقوية الأمان
## تعزيز الأمان
تستخدم مساعدات صندوق حماية OpenShell التي تقرأ ملفات مساحة العمل البعيدة
واصف ملف مثبتًا لجذر مساحة العمل وتسير عبر الأسلاف انطلاقًا من هذا الواصف المثبت
بدلًا من إعادة تحليل المسار في كل قراءة. ومع إعادة التحقق من الهوية
في كل عملية، يمنع هذا استبدال الرابط الرمزي في منتصف الدورة أو
استبدال ربط مساحة العمل أثناء التشغيل من إعادة توجيه القراءات خارج
مساحة العمل البعيدة المقصودة.
- يُفتح جذر مساحة العمل مرة واحدة ويُثبَّت؛ وتعيد القراءات اللاحقة استخدام هذا الواصف.
- تسير عمليات اجتياز الأسلاف عبر إدخالات نسبية انطلاقًا من الواصف المثبت بحيث لا يمكن
إعادة توجيهها باستبدال دليل أعلى في المسار.
- يُعاد التحقق من هوية صندوق الحماية قبل كل قراءة، بحيث لا يستطيع
صندوق حماية أُعيد إنشاؤه أو أُعيد تعيينه أن يقدّم ملفات بصمت من مساحة عمل مختلفة.
يثبّت OpenShell واصف ملف جذر مساحة العمل ويعيد التحقق من هوية sandbox قبل كل
عملية قراءة، حتى لا تتمكن عمليات تبديل الروابط الرمزية أو إعادة تحميل مساحة العمل من
إعادة توجيه القراءات خارج مساحة العمل البعيدة المقصودة.
## القيود الحالية
- متصفح صندوق الحماية غير مدعوم في خلفية OpenShell.
- متصفح sandbox غير مدعوم على واجهة OpenShell الخلفية.
- لا ينطبق `sandbox.docker.binds` على OpenShell.
- تنطبق مفاتيح وقت التشغيل الخاصة بـ Docker تحت `sandbox.docker.*` فقط على
خلفية Docker.
- تنطبق مفاتيح ضبط وقت التشغيل الخاصة بـ Docker ضمن `sandbox.docker.*` على
واجهة Docker الخلفية فقط.
## كيف يعمل
1. يستدعي OpenClaw الأمر `openshell sandbox create` (مع العلامات `--from` و`--gateway` و
`--policy` و`--providers` و`--gpu` حسب الإعدادات).
2. يستدعي OpenClaw الأمر `openshell sandbox ssh-config <name>` للحصول على تفاصيل
اتصال SSH الخاصة بصندوق الحماية.
3. يكتب core إعدادات SSH إلى ملف مؤقت ويفتح جلسة SSH باستخدام
جسر نظام الملفات البعيد نفسه الموجود في خلفية SSH العامة.
4. في وضع `mirror`: يزامن من المحلي إلى البعيد قبل exec، ويشغّل، ثم يزامن مجددًا بعد exec.
5. في وضع `remote`: يهيّئ مرة واحدة عند الإنشاء، ثم يعمل مباشرة على مساحة العمل
البعيدة.
1. يستدعي OpenClaw الأمر `openshell sandbox create` (مع العلامات `--from` و`--gateway`،
و`--policy`، و`--providers`، و`--gpu` بحسب الإعداد).
2. يستدعي OpenClaw الأمر `openshell sandbox ssh-config <name>` للحصول على تفاصيل اتصال SSH
الخاصة بـ sandbox.
3. يكتب النظام الأساسي إعداد SSH إلى ملف مؤقت ويفتح جلسة SSH باستخدام
جسر نظام الملفات البعيد نفسه كما في واجهة SSH الخلفية العامة.
4. في وضع `mirror`: يزامن من المحلي إلى البعيد قبل exec، ثم يشغّل، ثم يزامن عودةً بعد exec.
5. في وضع `remote`: يهيّئ مرة واحدة عند الإنشاء، ثم يعمل مباشرةً على
مساحة العمل البعيدة.
## راجع أيضًا
- [Sandboxing](/ar/gateway/sandboxing) -- الأوضاع والنطاقات ومقارنة الخلفيات
- [Sandboxing](/ar/gateway/sandboxing) -- الأوضاع، والنطاقات، ومقارنة الواجهات الخلفية
- [Sandbox vs Tool Policy vs Elevated](/ar/gateway/sandbox-vs-tool-policy-vs-elevated) -- تصحيح الأدوات المحظورة
- [Multi-Agent Sandbox and Tools](/ar/tools/multi-agent-sandbox-tools) -- تجاوزات لكل وكيل
- [Sandbox CLI](/ar/cli/sandbox) -- أوامر `openclaw sandbox`

157
docs/ar/gateway/pairing.md
View File

@ -1,47 +1,47 @@
---
read_when:
- تنفيذ موافقات اقتران Node من دون واجهة macOS UI
- تنفيذ موافقات اقتران Node من دون واجهة macOS مستخدم
- إضافة تدفقات CLI للموافقة على العُقد البعيدة
- توسيع بروتوكول Gateway بإدارة Node
summary: اقتران Node المملوك لـ Gateway (الخيار B) لأجهزة iOS والعُقد البعيدة الأخرى
summary: اقتران Node المملوك لـ Gateway (الخيار B) لنظام iOS والعُقد البعيدة الأخرى
title: الاقتران المملوك لـ Gateway
x-i18n:
generated_at: "2026-04-23T07:25:06Z"
generated_at: "2026-04-23T13:59:36Z"
model: gpt-5.4
provider: openai
source_hash: adba3c833b57b1df117c57d3451598e3c84cd78dcc6e9811547cdbb101afda0b
source_hash: f644f2dd9a79140156646a78df2a83f0940e3db8160cb083453e43c108eacf3a
source_path: gateway/pairing.md
workflow: 15
---
# الاقتران المملوك لـ Gateway (الخيار B)
في الاقتران المملوك لـ Gateway، تكون **Gateway** هي مصدر الحقيقة بشأن العُقد
المسموح لها بالانضمام. وتمثل واجهات المستخدم (تطبيق macOS والعملاء المستقبليون) مجرد واجهات
للموافقة على الطلبات المعلّقة أو رفضها.
في الاقتران المملوك لـ Gateway، يكون **Gateway** هو مصدر الحقيقة بشأن العُقد
المسموح لها بالانضمام. وتكون واجهات المستخدم (تطبيق macOS، والعملاء المستقبليون)
مجرد واجهات أمامية توافق أو ترفض الطلبات المعلقة.
**مهم:** تستخدم عُقد WS **اقتران الأجهزة** (الدور `node`) أثناء `connect`.
يمثل `node.pair.*` مخزن اقتران منفصلًا ولا يتحكم في مصافحة WS.
هذا التدفق تستخدمه فقط العملاء الذين يستدعون `node.pair.*` صراحةً.
**مهم:** تستخدم عُقد WS **اقتران الجهاز** (الدور `node`) أثناء `connect`.
ويُعد `node.pair.*` مخزن اقتران منفصلًا ولا يتحكم في مصافحة WS.
فقط العملاء الذين يستدعون `node.pair.*` صراحةً يستخدمون هذا التدفق.
## المفاهيم
- **طلب معلّق**: عقدة طلبت الانضمام؛ وتتطلب موافقة.
- **عقدة مقترنة**: عقدة تمت الموافقة عليها وصدر لها رمز مصادقة.
- **النقل**: تقوم نقطة نهاية Gateway WS بتمرير الطلبات، لكنها لا تقرر
- **طلب معلق**: عقدة طلبت الانضمام؛ ويتطلب موافقة.
- **عقدة مقترنة**: عقدة تمت الموافقة عليها مع إصدار رمز مصادقة لها.
- **النقل**: تقوم نقطة نهاية Gateway WS بتمرير الطلبات لكنها لا تقرر
العضوية. (تمت إزالة دعم جسر TCP القديم.)
## كيف يعمل الاقتران
1. تتصل عقدة بـ Gateway WS وتطلب الاقتران.
2. تخزّن Gateway **طلبًا معلّقًا** وتصدر الحدث `node.pair.requested`.
3. تقوم بالموافقة على الطلب أو رفضه (عبر CLI أو UI).
4. عند الموافقة، تصدر Gateway **رمزًا جديدًا** (يتم تدوير الرموز عند إعادة الاقتران).
5. تعيد العقدة الاتصال باستخدام الرمز، وتصبح الآن "مقترنة".
2. يخزن Gateway **طلبًا معلقًا** ويطلق `node.pair.requested`.
3. تقوم بالموافقة على الطلب أو رفضه (عبر CLI أو واجهة المستخدم).
4. عند الموافقة، يصدر Gateway **رمزًا جديدًا** (يتم تدوير الرموز عند إعادة الاقتران).
5. تعيد العقدة الاتصال باستخدام الرمز وتصبح الآن “مقترنة”.
تنتهي صلاحية الطلبات المعلّقة تلقائيًا بعد **5 دقائق**.
تنتهي صلاحية الطلبات المعلقة تلقائيًا بعد **5 دقائق**.
## سير عمل CLI (مناسب للوضع headless)
## سير عمل CLI (مناسب للوضع دون واجهة)
```bash
openclaw nodes pending
@ -51,33 +51,34 @@ openclaw nodes status
openclaw nodes rename --node <id|name|ip> --name "Living Room iPad"
```
يعرض `nodes status` العُقد المقترنة/المتصلة وإمكاناتها.
يعرض `nodes status` العُقد المقترنة/المتصلة وقدراتها.
## واجهة API (بروتوكول gateway)
## سطح API (بروتوكول gateway)
الأحداث:
- `node.pair.requested` — يُصدر عند إنشاء طلب معلّق جديد.
- `node.pair.resolved` — يُصدر عند الموافقة على طلب أو رفضه أو انتهاء صلاحيته.
- `node.pair.requested` — يُطلق عند إنشاء طلب معلق جديد.
- `node.pair.resolved` — يُطلق عند الموافقة على طلب أو رفضه أو انتهاء صلاحيته.
الأساليب:
- `node.pair.request` — إنشاء طلب معلّق أو إعادة استخدامه.
- `node.pair.list` — عرض العُقد المعلّقة + المقترنة (`operator.pairing`).
- `node.pair.approve` — الموافقة على طلب معلّق (مع إصدار رمز).
- `node.pair.reject` — رفض طلب معلّق.
- `node.pair.request` — إنشاء طلب معلق أو إعادة استخدامه.
- `node.pair.list` — عرض العُقد المعلقة + المقترنة (`operator.pairing`).
- `node.pair.approve` — الموافقة على طلب معلق (يُصدر رمزًا).
- `node.pair.reject` — رفض طلب معلق.
- `node.pair.verify` — التحقق من `{ nodeId, token }`.
ملاحظات:
- يمثّل `node.pair.request` عملية متماثلة لكل عقدة: تعيد الاستدعاءات المتكررة
الطلب المعلّق نفسه.
- تعمل الطلبات المتكررة للعقدة المعلّقة نفسها أيضًا على تحديث
بيانات وصف العقدة المخزنة وأحدث لقطة للأوامر المعلنة المسموح بها لرؤية المشغّل.
- تُنشئ الموافقة **دائمًا** رمزًا جديدًا؛ ولا يُعاد أي رمز مطلقًا من
- `node.pair.request` متكرر آمن لكل عقدة: تعيد الاستدعاءات المتكررة
الطلب المعلق نفسه.
- تؤدي الطلبات المتكررة للعقدة المعلقة نفسها أيضًا إلى تحديث
البيانات الوصفية المخزنة للعقدة وأحدث لقطة للأوامر المعلنة والمدرجة في قائمة السماح
لإتاحة الرؤية للمشغل.
- تؤدي الموافقة **دائمًا** إلى إنشاء رمز جديد؛ ولا يُعاد أي رمز من
`node.pair.request`.
- قد تتضمن الطلبات `silent: true` كتلميح لتدفقات الموافقة التلقائية.
- تستخدم `node.pair.approve` الأوامر المعلنة في الطلب المعلّق لفرض
- يستخدم `node.pair.approve` الأوامر المعلنة للطلب المعلق لفرض
نطاقات موافقة إضافية:
- طلب بلا أوامر: `operator.pairing`
- طلب أوامر غير تنفيذية: `operator.pairing` + `operator.write`
@ -86,72 +87,80 @@ openclaw nodes rename --node <id|name|ip> --name "Living Room iPad"
مهم:
- يمثل اقتران Node تدفق ثقة/هوية بالإضافة إلى إصدار الرموز.
- وهو **لا** يثبّت سطح أوامر Node الحي لكل عقدة.
- تأتي أوامر Node الحية مما تعلنه العقدة عند الاتصال بعد تطبيق
سياسة أوامر Node العامة في gateway (`gateway.nodes.allowCommands` /
- اقتران Node هو تدفق ثقة/هوية بالإضافة إلى إصدار رمز.
- وهو لا يثبّت سطح أوامر Node الحية لكل عقدة.
- تأتي أوامر Node الحية من الأوامر التي تعلنها العقدة عند الاتصال بعد تطبيق
سياسة أوامر العُقد العامة في gateway (`gateway.nodes.allowCommands` /
`denyCommands`).
- تعيش سياسة السماح/الطلب الخاصة بـ `system.run` لكل عقدة على العقدة نفسها ضمن
- توجد سياسة السماح/السؤال الخاصة بـ `system.run` لكل عقدة على العقدة نفسها ضمن
`exec.approvals.node.*`، وليس في سجل الاقتران.
## بوابة أوامر Node ‏(2026.3.31+)
## تقييد أوامر Node ‏(2026.3.31+)
<Warning>
**تغيير غير متوافق:** بدءًا من `2026.3.31`، تُعطَّل أوامر Node إلى أن تتم الموافقة على اقتران Node. لم يعد اقتران الجهاز وحده كافيًا لكشف أوامر Node المعلنة.
**تغيير جذري:** بدءًا من `2026.3.31`، تُعطَّل أوامر Node إلى أن تتم الموافقة على اقتران Node. ولم يعد اقتران الجهاز وحده كافيًا لإظهار أوامر Node المعلنة.
</Warning>
عندما تتصل عقدة لأول مرة، يُطلب الاقتران تلقائيًا. وحتى تتم الموافقة على طلب الاقتران، تتم تصفية جميع أوامر Node المعلّقة من تلك العقدة ولن تُنفَّذ. وبمجرد إنشاء الثقة عبر الموافقة على الاقتران، تصبح أوامر العقدة المعلنة متاحة مع الخضوع لسياسة الأوامر العادية.
عندما تتصل عقدة لأول مرة، يُطلب الاقتران تلقائيًا. وحتى تتم الموافقة
على طلب الاقتران، تُصفّى جميع أوامر Node المعلقة من تلك العقدة ولن تُنفّذ.
وبمجرد إنشاء الثقة عبر الموافقة على الاقتران، تصبح أوامر العقدة المعلنة
متاحة وفقًا لسياسة الأوامر المعتادة.
وهذا يعني:
- يجب الآن على العُقد التي كانت تعتمد سابقًا على اقتران الجهاز وحده لكشف الأوامر إكمال اقتران Node.
- تُسقَط الأوامر التي وُضعت في الطابور قبل الموافقة على الاقتران، ولا تُؤجَّل.
- يجب الآن على العُقد التي كانت تعتمد سابقًا على اقتران الجهاز وحده لإظهار الأوامر إكمال اقتران Node.
- الأوامر المصطفة قبل الموافقة على الاقتران تُسقط ولا تؤجَّل.
## حدود الثقة لأحداث Node ‏(2026.3.31+)
<Warning>
**تغيير غير متوافق:** تبقى التشغيلات الصادرة من Node الآن ضمن سطح موثوق منخفض.
**تغيير جذري:** أصبحت العمليات المنطلقة من Node الآن محصورة في سطح ثقة مخفَّض.
</Warning>
تُقيَّد الملخّصات الصادرة من Node وأحداث الجلسة المرتبطة بها ضمن السطح الموثوق المقصود. وقد تحتاج التدفقات المعتمدة على الإشعارات أو التي تحفّزها Node والتي كانت تعتمد سابقًا على وصول أوسع إلى أدوات المضيف أو الجلسة إلى تعديل. ويضمن هذا التشديد الأمني أن أحداث Node لا يمكنها التصعيد إلى وصول إلى أدوات على مستوى المضيف يتجاوز ما تسمح به حدود الثقة الخاصة بالعقدة.
تُقيَّد الملخصات الصادرة من Node وأحداث الجلسة ذات الصلة على سطح الثقة
المقصود. وقد تحتاج التدفقات المعتمدة على الإشعارات أو المشغلة بواسطة Node
التي كانت تعتمد سابقًا على وصول أوسع إلى أدوات المضيف أو الجلسة إلى تعديل.
ويضمن هذا التعزيز الأمني أن أحداث Node لا يمكنها التصعيد إلى وصول على مستوى
أدوات المضيف بما يتجاوز ما تسمح به حدود الثقة الخاصة بالعقدة.
## الموافقة التلقائية (تطبيق macOS)
يمكن لتطبيق macOS اختياريًا محاولة **موافقة صامتة** عندما:
- تكون الطلبات معلّمة بـ `silent`، و
- يتمكن التطبيق من التحقق من اتصال SSH إلى مضيف gateway باستخدام المستخدم نفسه.
- يُعلَّم الطلب بأنه `silent`، و
- يتمكن التطبيق من التحقق من اتصال SSH بمضيف gateway باستخدام المستخدم نفسه.
إذا فشلت الموافقة الصامتة، فإنه يعود إلى مطالبة "Approve/Reject" العادية.
إذا فشلت الموافقة الصامتة، يعود إلى نافذة “موافقة/رفض” المعتادة.
## الموافقة التلقائية لترقية البيانات الوصفية
عندما تعيد أداة مقترنة بالفعل الاتصال مع تغييرات غير حساسة فقط في
عندما يعيد جهاز مقترن بالفعل الاتصال مع تغييرات غير حساسة فقط في
البيانات الوصفية (مثل اسم العرض أو تلميحات منصة العميل)، يتعامل OpenClaw
مع ذلك على أنه `metadata-upgrade`. تكون الموافقة الصامتة التلقائية ضيقة النطاق:
فهي تنطبق فقط على إعادة اتصال CLI/المساعدات المحلية الموثوقة التي أثبتت بالفعل
امتلاك الرمز المشترك أو كلمة المرور عبر local loopback. أما العملاء عبر المتصفح/واجهة Control UI
والعملاء البعيدون فلا يزالون يستخدمون تدفق إعادة الموافقة الصريح. ولا تكون ترقيات
النطاق (من read إلى write/admin) وتغييرات المفتاح العام **مؤهلة**
للموافقة التلقائية لترقية البيانات الوصفية — بل تظل طلبات إعادة موافقة صريحة.
مع ذلك باعتباره `metadata-upgrade`. وتبقى الموافقة الصامتة التلقائية ضيقة النطاق:
فهي تنطبق فقط على عمليات إعادة الاتصال الموثوقة من CLI/المساعد المحلي التي أثبتت
بالفعل امتلاك الرمز المشترك أو كلمة المرور عبر loopback. أما عملاء المتصفح/واجهة Control
والعملاء البعيدون فما زالوا يستخدمون تدفق إعادة الموافقة الصريح. أما ترقيات النطاق
(من القراءة إلى الكتابة/الإدارة) وتغييرات المفتاح العام فهي **غير** مؤهلة
للموافقة التلقائية لترقية البيانات الوصفية — وتظل طلبات إعادة موافقة صريحة.
## مساعدات الاقتران عبر QR
## أدوات مساعدة للاقتران عبر QR
يقوم `/pair qr` بعرض حمولة الاقتران كوسائط منظّمة بحيث يمكن للعملاء على
الهواتف المحمولة والمتصفحات مسحها مباشرةً. كما أن حذف الجهاز يجري الآن أيضًا
تنظيفًا لطلبات الاقتران المعلّقة القديمة الخاصة بمعرّف الجهاز نفسه، لذلك لم يعد
`nodes pending` يعرض صفوفًا يتيمة بعد الإلغاء.
يعرض `/pair qr` حمولة الاقتران كوسائط منظمة بحيث تتمكن
العملاء على الأجهزة المحمولة وعملاء المتصفح من مسحها مباشرة.
يؤدي حذف جهاز أيضًا إلى تنظيف أي طلبات اقتران معلقة قديمة لذلك
المعرّف الخاص بالجهاز، بحيث لا يعرض `nodes pending` صفوفًا يتيمة بعد الإلغاء.
## المحلية والرؤوس المُمرَّرة
يعامل اقتران Gateway الاتصال على أنه loopback فقط عندما يتفق كل من المقبس الخام
وأي دليل من الوكيل upstream على ذلك. فإذا وصل طلب عبر loopback لكنه حمل
رؤوس `X-Forwarded-For` / `X-Forwarded-Host` / `X-Forwarded-Proto` تشير إلى
أصل غير محلي، فإن هذا الدليل من الرؤوس المُمرَّرة يُسقط ادعاء المحلية عبر loopback.
وعندها يتطلب مسار الاقتران موافقة صريحة بدلًا من التعامل الصامت مع الطلب
على أنه اتصال من المضيف نفسه. راجع
[مصادقة الوكيل الموثوق](/ar/gateway/trusted-proxy-auth) للاطلاع على القاعدة المكافئة في
مصادقة المشغّل.
يتعامل Gateway pairing مع الاتصال على أنه loopback فقط عندما تتفق
المقبس الخام وأي أدلة من proxy في المنبع معًا. وإذا وصل طلب عبر loopback لكنه
يحمل رؤوس `X-Forwarded-For` / `X-Forwarded-Host` / `X-Forwarded-Proto`
تشير إلى أصل غير محلي، فإن أدلة الرؤوس المُمرَّرة هذه تُبطل ادعاء المحلية عبر
loopback. وعندها يتطلب مسار الاقتران موافقة صريحة بدلًا من
اعتبار الطلب اتصالًا من المضيف نفسه بشكل صامت. راجع
[Trusted Proxy Auth](/ar/gateway/trusted-proxy-auth) للاطلاع على القاعدة المكافئة في
مصادقة المشغل.
## التخزين (محلي، خاص)
@ -160,15 +169,15 @@ openclaw nodes rename --node <id|name|ip> --name "Living Room iPad"
- `~/.openclaw/nodes/paired.json`
- `~/.openclaw/nodes/pending.json`
إذا قمت بتجاوز `OPENCLAW_STATE_DIR`، فسينتقل مجلد `nodes/` معه.
إذا قمت بتجاوز `OPENCLAW_STATE_DIR`، ينتقل مجلد `nodes/` معه.
ملاحظات أمنية:
- الرموز أسرار؛ لذا تعامل مع `paired.json` على أنه حساس.
- يتطلب تدوير الرمز إعادة الموافقة (أو حذف إدخال العقدة).
- الرموز أسرار؛ تعامل مع `paired.json` على أنه حساس.
- يتطلب تدوير الرمز إعادة موافقة (أو حذف إدخال العقدة).
## سلوك النقل
- النقل **عديم الحالة**؛ فهو لا يخزّن العضوية.
- إذا كانت Gateway غير متصلة أو كان الاقتران معطّلًا، فلن تتمكن العُقد من الاقتران.
- إذا كانت Gateway في الوضع البعيد، فسيظل الاقتران يتم مقابل مخزن Gateway البعيدة.
- النقل **عديم الحالة**؛ فهو لا يخزن العضوية.
- إذا كان Gateway غير متصل أو كان الاقتران معطلًا، فلا يمكن للعُقد الاقتران.
- إذا كان Gateway في الوضع البعيد، يظل الاقتران يحدث مقابل مخزن Gateway البعيد.

137
docs/ar/gateway/security/audit-checks.md Normal file
View File

@ -0,0 +1,137 @@
---
read_when:
- لقد رأيت ``checkId`` محددًا في مخرجات ``openclaw security audit`` وتريد معرفة معناه.
- تحتاج إلى مفتاح/مسار الإصلاح لنتيجة معيّنة.
- أنت تقوم بفرز الشدة عبر تشغيل للتدقيق الأمني.
summary: فهرس مرجعي لمعرّفات الفحص `checkIds` الصادرة عن openclaw security audit
title: فحوصات التدقيق الأمني
x-i18n:
generated_at: "2026-04-23T14:00:10Z"
model: gpt-5.4
provider: openai
source_hash: b53a8dc798ecc8c37be43758b741c68772b10c92323ab3d26592d7b3cc2c795e
source_path: gateway/security/audit-checks.md
workflow: 15
---
# فحوصات التدقيق الأمني
يُصدر `openclaw security audit` نتائج منظَّمة مقيّدة بواسطة `checkId`. وتُعد هذه
الصفحة فهرسًا مرجعيًا لهذه المعرّفات. وللاطلاع على نموذج التهديد العام
وإرشادات التقوية، راجع [الأمان](/ar/gateway/security).
قيم `checkId` عالية الإشارة التي يُرجَّح أن تراها في عمليات النشر الفعلية (القائمة
غير شاملة):
| `checkId` | الشدة | سبب الأهمية | مفتاح/مسار الإصلاح الأساسي | إصلاح تلقائي |
| ------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- | ------------ |
| `fs.state_dir.perms_world_writable` | critical | يمكن لمستخدمين/عمليات أخرى تعديل حالة OpenClaw بالكامل | أذونات نظام الملفات على `~/.openclaw` | نعم |
| `fs.state_dir.perms_group_writable` | warn | يمكن لمستخدمي المجموعة تعديل حالة OpenClaw بالكامل | أذونات نظام الملفات على `~/.openclaw` | نعم |
| `fs.state_dir.perms_readable` | warn | دليل الحالة قابل للقراءة من الآخرين | أذونات نظام الملفات على `~/.openclaw` | نعم |
| `fs.state_dir.symlink` | warn | يصبح هدف دليل الحالة حدّ ثقة آخر | تخطيط نظام الملفات لدليل الحالة | لا |
| `fs.config.perms_writable` | critical | يمكن للآخرين تغيير سياسة المصادقة/الأدوات/التكوين | أذونات نظام الملفات على `~/.openclaw/openclaw.json` | نعم |
| `fs.config.symlink` | warn | ملفات التكوين المرتبطة برمز symlink غير مدعومة للكتابة وتضيف حدّ ثقة آخر | استبداله بملف تكوين عادي أو توجيه `OPENCLAW_CONFIG_PATH` إلى الملف الحقيقي | لا |
| `fs.config.perms_group_readable` | warn | يمكن لمستخدمي المجموعة قراءة رموز/إعدادات التكوين | أذونات نظام الملفات على ملف التكوين | نعم |
| `fs.config.perms_world_readable` | critical | قد يكشف التكوين عن الرموز/الإعدادات | أذونات نظام الملفات على ملف التكوين | نعم |
| `fs.config_include.perms_writable` | critical | يمكن للآخرين تعديل ملف تضمين التكوين | أذونات ملف التضمين المشار إليه من `openclaw.json` | نعم |
| `fs.config_include.perms_group_readable` | warn | يمكن لمستخدمي المجموعة قراءة الأسرار/الإعدادات المضمّنة | أذونات ملف التضمين المشار إليه من `openclaw.json` | نعم |
| `fs.config_include.perms_world_readable` | critical | الأسرار/الإعدادات المضمّنة قابلة للقراءة من الجميع | أذونات ملف التضمين المشار إليه من `openclaw.json` | نعم |
| `fs.auth_profiles.perms_writable` | critical | يمكن للآخرين حقن بيانات اعتماد النماذج المخزنة أو استبدالها | أذونات `agents/<agentId>/agent/auth-profiles.json` | نعم |
| `fs.auth_profiles.perms_readable` | warn | يمكن للآخرين قراءة مفاتيح API ورموز OAuth | أذونات `agents/<agentId>/agent/auth-profiles.json` | نعم |
| `fs.credentials_dir.perms_writable` | critical | يمكن للآخرين تعديل حالة اقتران القنوات/بيانات الاعتماد | أذونات نظام الملفات على `~/.openclaw/credentials` | نعم |
| `fs.credentials_dir.perms_readable` | warn | يمكن للآخرين قراءة حالة بيانات اعتماد القنوات | أذونات نظام الملفات على `~/.openclaw/credentials` | نعم |
| `fs.sessions_store.perms_readable` | warn | يمكن للآخرين قراءة نصوص الجلسات/البيانات الوصفية | أذونات مخزن الجلسات | نعم |
| `fs.log_file.perms_readable` | warn | يمكن للآخرين قراءة السجلات المنقحة لكنها ما تزال حساسة | أذونات ملف سجل gateway | نعم |
| `fs.synced_dir` | warn | يوسّع وضع الحالة/التكوين في iCloud/Dropbox/Drive نطاق كشف الرموز/النصوص | نقل التكوين/الحالة خارج المجلدات المتزامنة | لا |
| `gateway.bind_no_auth` | critical | ربط بعيد من دون سر مشترك | `gateway.bind`، `gateway.auth.*` | لا |
| `gateway.loopback_no_auth` | critical | قد تصبح loopback المعكوسة عبر proxy غير موثقة | `gateway.auth.*`، إعداد proxy | لا |
| `gateway.trusted_proxies_missing` | warn | رؤوس reverse-proxy موجودة ولكنها غير موثوقة | `gateway.trustedProxies` | لا |
| `gateway.http.no_auth` | warn/critical | يمكن الوصول إلى واجهات Gateway HTTP API مع `auth.mode="none"` | `gateway.auth.mode`، `gateway.http.endpoints.*` | لا |
| `gateway.http.session_key_override_enabled` | info | يمكن لمستدعي HTTP API تجاوز `sessionKey` | `gateway.http.allowSessionKeyOverride` | لا |
| `gateway.tools_invoke_http.dangerous_allow` | warn/critical | يعيد تمكين الأدوات الخطرة عبر HTTP API | `gateway.tools.allow` | لا |
| `gateway.nodes.allow_commands_dangerous` | warn/critical | يفعّل أوامر Node عالية التأثير (الكاميرا/الشاشة/جهات الاتصال/التقويم/SMS) | `gateway.nodes.allowCommands` | لا |
| `gateway.nodes.deny_commands_ineffective` | warn | إدخالات المنع الشبيهة بالأنماط لا تطابق نص shell أو المجموعات | `gateway.nodes.denyCommands` | لا |
| `gateway.tailscale_funnel` | critical | تعرض على الإنترنت العام | `gateway.tailscale.mode` | لا |
| `gateway.tailscale_serve` | info | تم تفعيل التعرض داخل Tailnet عبر Serve | `gateway.tailscale.mode` | لا |
| `gateway.control_ui.allowed_origins_required` | critical | Control UI غير loopback من دون قائمة سماح صريحة لأصول المتصفح | `gateway.controlUi.allowedOrigins` | لا |
| `gateway.control_ui.allowed_origins_wildcard` | warn/critical | يؤدي `allowedOrigins=["*"]` إلى تعطيل قائمة سماح أصول المتصفح | `gateway.controlUi.allowedOrigins` | لا |
| `gateway.control_ui.host_header_origin_fallback` | warn/critical | يفعّل الرجوع إلى أصل Host-header (إضعاف تقوية DNS rebinding) | `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback` | لا |
| `gateway.control_ui.insecure_auth` | warn | تم تفعيل مفتاح التوافق للمصادقة غير الآمنة | `gateway.controlUi.allowInsecureAuth` | لا |
| `gateway.control_ui.device_auth_disabled` | critical | يعطّل التحقق من هوية الجهاز | `gateway.controlUi.dangerouslyDisableDeviceAuth` | لا |
| `gateway.real_ip_fallback_enabled` | warn/critical | قد يؤدي الوثوق في الرجوع إلى `X-Real-IP` إلى انتحال IP المصدر بسبب سوء إعداد proxy | `gateway.allowRealIpFallback`، `gateway.trustedProxies` | لا |
| `gateway.token_too_short` | warn | يسهل تخمين الرمز المشترك القصير بالقوة الغاشمة | `gateway.auth.token` | لا |
| `gateway.auth_no_rate_limit` | warn | تزيد المصادقة المكشوفة من دون تحديد المعدل من خطر القوة الغاشمة | `gateway.auth.rateLimit` | لا |
| `gateway.trusted_proxy_auth` | critical | تصبح هوية proxy الآن حدّ المصادقة | `gateway.auth.mode="trusted-proxy"` | لا |
| `gateway.trusted_proxy_no_proxies` | critical | مصادقة trusted-proxy من دون عناوين IP موثوقة للـ proxy غير آمنة | `gateway.trustedProxies` | لا |
| `gateway.trusted_proxy_no_user_header` | critical | لا تستطيع مصادقة trusted-proxy تحديد هوية المستخدم بأمان | `gateway.auth.trustedProxy.userHeader` | لا |
| `gateway.trusted_proxy_no_allowlist` | warn | تقبل مصادقة trusted-proxy أي مستخدم upstream موثَّق | `gateway.auth.trustedProxy.allowUsers` | لا |
| `checkId` | الشدة | سبب الأهمية | مفتاح/مسار الإصلاح الأساسي | إصلاح تلقائي |
| ------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- | ------------ |
| `gateway.probe_auth_secretref_unavailable` | warn | تعذّر على الفحص العميق حل SecretRefs الخاصة بالمصادقة في مسار الأوامر هذا | مصدر مصادقة الفحص العميق / توفر SecretRef | لا |
| `gateway.probe_failed` | warn/critical | فشل الفحص الحي لـ Gateway | إمكانية الوصول إلى gateway/المصادقة | لا |
| `discovery.mdns_full_mode` | warn/critical | يعلن وضع mDNS الكامل عن بيانات `cliPath`/`sshPort` الوصفية على الشبكة المحلية | `discovery.mdns.mode`، `gateway.bind` | لا |
| `config.insecure_or_dangerous_flags` | warn | تم تفعيل أي رايات تصحيح غير آمنة/خطرة | مفاتيح متعددة (راجع تفاصيل النتيجة) | لا |
| `config.secrets.gateway_password_in_config` | warn | كلمة مرور Gateway مخزنة مباشرة في التكوين | `gateway.auth.password` | لا |
| `config.secrets.hooks_token_in_config` | warn | رمز bearer الخاص بالخطافات مخزن مباشرة في التكوين | `hooks.token` | لا |
| `hooks.token_reuse_gateway_token` | critical | رمز دخول الخطافات يفتح أيضًا مصادقة Gateway | `hooks.token`، `gateway.auth.token` | لا |
| `hooks.token_too_short` | warn | يسهل تخمين رمز دخول الخطافات بالقوة الغاشمة | `hooks.token` | لا |
| `hooks.default_session_key_unset` | warn | تتشعب عمليات hook agent إلى جلسات مولَّدة لكل طلب | `hooks.defaultSessionKey` | لا |
| `hooks.allowed_agent_ids_unrestricted` | warn/critical | يمكن لمستدعي الخطافات الموثقين التوجيه إلى أي agent مضبوط | `hooks.allowedAgentIds` | لا |
| `hooks.request_session_key_enabled` | warn/critical | يمكن للمستدعي الخارجي اختيار `sessionKey` | `hooks.allowRequestSessionKey` | لا |
| `hooks.request_session_key_prefixes_missing` | warn/critical | لا يوجد حد لأشكال مفاتيح الجلسات الخارجية | `hooks.allowedSessionKeyPrefixes` | لا |
| `hooks.path_root` | critical | مسار الخطافات هو `/`، ما يجعل المدخل أسهل تصادمًا أو سوء توجيه | `hooks.path` | لا |
| `hooks.installs_unpinned_npm_specs` | warn | سجلات تثبيت الخطافات غير مثبتة على مواصفات npm غير قابلة للتغيير | بيانات تثبيت الخطافات الوصفية | لا |
| `hooks.installs_missing_integrity` | warn | سجلات تثبيت الخطافات تفتقر إلى بيانات السلامة الوصفية | بيانات تثبيت الخطافات الوصفية | لا |
| `hooks.installs_version_drift` | warn | سجلات تثبيت الخطافات انجرفت عن الحِزم المثبتة | بيانات تثبيت الخطافات الوصفية | لا |
| `logging.redact_off` | warn | تتسرب القيم الحساسة إلى السجلات/الحالة | `logging.redactSensitive` | نعم |
| `browser.control_invalid_config` | warn | إعداد Browser control غير صالح قبل وقت التشغيل | `browser.*` | لا |
| `browser.control_no_auth` | critical | تم كشف Browser control من دون مصادقة بالرمز/كلمة المرور | `gateway.auth.*` | لا |
| `browser.remote_cdp_http` | warn | يفتقر CDP البعيد عبر HTTP العادي إلى تشفير النقل | ملف تعريف المتصفح `cdpUrl` | لا |
| `browser.remote_cdp_private_host` | warn | يستهدف CDP البعيد مضيفًا خاصًا/داخليًا | ملف تعريف المتصفح `cdpUrl`، `browser.ssrfPolicy.*` | لا |
| `sandbox.docker_config_mode_off` | warn | يوجد إعداد Docker الخاص بـ Sandbox لكنه غير نشط | `agents.*.sandbox.mode` | لا |
| `sandbox.bind_mount_non_absolute` | warn | قد تُحل bind mounts النسبية بشكل غير متوقع | `agents.*.sandbox.docker.binds[]` | لا |
| `sandbox.dangerous_bind_mount` | critical | تستهدف bind mount الخاصة بـ Sandbox مسارات نظام أو بيانات اعتماد أو Docker socket محظورة | `agents.*.sandbox.docker.binds[]` | لا |
| `sandbox.dangerous_network_mode` | critical | تستخدم شبكة Docker الخاصة بـ Sandbox وضع `host` أو `container:*` للانضمام إلى namespace | `agents.*.sandbox.docker.network` | لا |
| `sandbox.dangerous_seccomp_profile` | critical | يضعف ملف seccomp الخاص بـ Sandbox عزل الحاوية | `agents.*.sandbox.docker.securityOpt` | لا |
| `sandbox.dangerous_apparmor_profile` | critical | يضعف ملف AppArmor الخاص بـ Sandbox عزل الحاوية | `agents.*.sandbox.docker.securityOpt` | لا |
| `sandbox.browser_cdp_bridge_unrestricted` | warn | جسر متصفح Sandbox مكشوف من دون تقييد لنطاق المصدر | `sandbox.browser.cdpSourceRange` | لا |
| `sandbox.browser_container.non_loopback_publish` | critical | تنشر حاوية المتصفح الحالية CDP على واجهات غير loopback | إعدادات نشر حاوية Sandbox الخاصة بالمتصفح | لا |
| `sandbox.browser_container.hash_label_missing` | warn | حاوية المتصفح الحالية تسبق تسميات hash الخاصة بالتكوين الحالي | `openclaw sandbox recreate --browser --all` | لا |
| `sandbox.browser_container.hash_epoch_stale` | warn | حاوية المتصفح الحالية تسبق حقبة تكوين المتصفح الحالية | `openclaw sandbox recreate --browser --all` | لا |
| `tools.exec.host_sandbox_no_sandbox_defaults` | warn | يفشل `exec host=sandbox` بشكل مغلق عندما يكون Sandbox معطلًا | `tools.exec.host`، `agents.defaults.sandbox.mode` | لا |
| `tools.exec.host_sandbox_no_sandbox_agents` | warn | يفشل `exec host=sandbox` لكل agent بشكل مغلق عندما يكون Sandbox معطلًا | `agents.list[].tools.exec.host`، `agents.list[].sandbox.mode` | لا |
| `tools.exec.security_full_configured` | warn/critical | يعمل تنفيذ المضيف مع `security="full"` | `tools.exec.security`، `agents.list[].tools.exec.security` | لا |
| `tools.exec.auto_allow_skills_enabled` | warn | تثق موافقات exec ضمنيًا في صناديق Skills التنفيذية | `~/.openclaw/exec-approvals.json` | لا |
| `tools.exec.allowlist_interpreter_without_strict_inline_eval` | warn | تسمح قوائم سماح المفسر بالتقييم المضمن من دون فرض إعادة موافقة | `tools.exec.strictInlineEval`، `agents.list[].tools.exec.strictInlineEval`، قائمة سماح موافقات exec | لا |
| `tools.exec.safe_bins_interpreter_unprofiled` | warn | توسّع صناديق المفسر/وقت التشغيل في `safeBins` بدون ملفات تعريف صريحة مخاطر التنفيذ | `tools.exec.safeBins`، `tools.exec.safeBinProfiles`، `agents.list[].tools.exec.*` | لا |
| `tools.exec.safe_bins_broad_behavior` | warn | تُضعف الأدوات ذات السلوك الواسع في `safeBins` نموذج الثقة منخفضة المخاطر لمرشح stdin | `tools.exec.safeBins`، `agents.list[].tools.exec.safeBins` | لا |
| `tools.exec.safe_bin_trusted_dirs_risky` | warn | تتضمن `safeBinTrustedDirs` أدلة قابلة للتعديل أو محفوفة بالمخاطر | `tools.exec.safeBinTrustedDirs`، `agents.list[].tools.exec.safeBinTrustedDirs` | لا |
| `skills.workspace.symlink_escape` | warn | يتم حل `skills/**/SKILL.md` في مساحة العمل خارج جذر مساحة العمل (انجراف سلسلة symlink) | حالة نظام الملفات لـ `skills/**` في مساحة العمل | لا |
| `plugins.extensions_no_allowlist` | warn | تُثبَّت Plugins من دون قائمة سماح صريحة للـ Plugin | `plugins.allowlist` | لا |
| `plugins.installs_unpinned_npm_specs` | warn | سجلات تثبيت Plugins غير مثبتة على مواصفات npm غير قابلة للتغيير | بيانات تثبيت Plugins الوصفية | لا |
| `checkId` | الشدة | سبب الأهمية | مفتاح/مسار الإصلاح الأساسي | إصلاح تلقائي |
| ------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- | ------------ |
| `plugins.installs_missing_integrity` | warn | سجلات تثبيت Plugins تفتقر إلى بيانات السلامة الوصفية | بيانات تثبيت Plugins الوصفية | لا |
| `plugins.installs_version_drift` | warn | سجلات تثبيت Plugins انجرفت عن الحِزم المثبتة | بيانات تثبيت Plugins الوصفية | لا |
| `plugins.code_safety` | warn/critical | عثر فحص شيفرة Plugin على أنماط مريبة أو خطرة | شيفرة Plugin / مصدر التثبيت | لا |
| `plugins.code_safety.entry_path` | warn | يشير مسار إدخال Plugin إلى مواقع مخفية أو داخل `node_modules` | `entry` في بيان Plugin | لا |
| `plugins.code_safety.entry_escape` | critical | يخرج إدخال Plugin خارج دليل Plugin | `entry` في بيان Plugin | لا |
| `plugins.code_safety.scan_failed` | warn | تعذّر إكمال فحص شيفرة Plugin | مسار Plugin / بيئة الفحص | لا |
| `skills.code_safety` | warn/critical | تحتوي بيانات التثبيت الوصفية/شيفرة Skills على أنماط مريبة أو خطرة | مصدر تثبيت Skills | لا |
| `skills.code_safety.scan_failed` | warn | تعذّر إكمال فحص شيفرة Skills | بيئة فحص Skills | لا |
| `security.exposure.open_channels_with_exec` | warn/critical | يمكن للغرف المشتركة/العامة الوصول إلى agents المفعّل لها exec | `channels.*.dmPolicy`، `channels.*.groupPolicy`، `tools.exec.*`، `agents.list[].tools.exec.*` | لا |
| `security.exposure.open_groups_with_elevated` | critical | تؤدي المجموعات المفتوحة مع الأدوات المرفوعة الصلاحية إلى مسارات حقن أوامر عالية الأثر | `channels.*.groupPolicy`، `tools.elevated.*` | لا |
| `security.exposure.open_groups_with_runtime_or_fs` | critical/warn | يمكن للمجموعات المفتوحة الوصول إلى أدوات الأوامر/الملفات من دون حواجز Sandbox/مساحة العمل | `channels.*.groupPolicy`، `tools.profile/deny`، `tools.fs.workspaceOnly`، `agents.*.sandbox.mode` | لا |
| `security.trust_model.multi_user_heuristic` | warn | يبدو التكوين متعدد المستخدمين بينما نموذج ثقة gateway هو مساعد شخصي | فصل حدود الثقة، أو تقوية المستخدمين المشتركين (`sandbox.mode`، منع الأدوات/تقييد مساحة العمل) | لا |
| `tools.profile_minimal_overridden` | warn | تتجاوز إعدادات agent العامة ملف التعريف الأدنى الشامل | `agents.list[].tools.profile` | لا |
| `plugins.tools_reachable_permissive_policy` | warn | يمكن الوصول إلى أدوات extension في سياقات متساهلة | `tools.profile` + السماح/المنع للأدوات | لا |
| `models.legacy` | warn | ما تزال عائلات النماذج القديمة مضبوطة | اختيار النموذج | لا |
| `models.weak_tier` | warn | النماذج المضبوطة دون المستويات الموصى بها حاليًا | اختيار النموذج | لا |
| `models.small_params` | critical/info | ترفع النماذج الصغيرة مع أسطح الأدوات غير الآمنة من خطر الحقن | اختيار النموذج + سياسة Sandbox/الأدوات | لا |
| `summary.attack_surface` | info | ملخص تجميعي لوضع المصادقة والقنوات والأدوات والتعرض | مفاتيح متعددة (راجع تفاصيل النتيجة) | لا |
## ذو صلة
- [الأمان](/ar/gateway/security)
- [التكوين](/ar/gateway/configuration)
- [مصادقة Trusted proxy](/ar/gateway/trusted-proxy-auth)

1307
docs/ar/gateway/security/index.md
View File

File diff suppressed because it is too large Load Diff

1195
docs/ar/help/testing.md
View File

File diff suppressed because it is too large Load Diff

1565
docs/ar/plugins/architecture.md
View File

File diff suppressed because it is too large Load Diff

270
docs/ar/plugins/bundles.md
View File

@ -1,43 +1,43 @@
---
read_when:
- أنت تريد تثبيت حزمة متوافقة مع Codex أو Claude أو Cursor
- أنت تحتاج إلى فهم كيفية قيام OpenClaw بربط محتوى الحزمة بالميزات الأصلية
- أنت تستكشف أخطاء اكتشاف الحِزم أو الإمكانات المفقودة وإصلاحها
summary: تثبيت واستخدام حِزم Codex وClaude وCursor كـ Plugins في OpenClaw
title: حِزم Plugin
- تريد تثبيت حزمة متوافقة مع Codex أو Claude أو Cursor
- تحتاج إلى فهم كيفية تحويل OpenClaw لمحتوى الحزمة إلى ميزات أصلية
- أنت تقوم بتصحيح اكتشاف الحزمة أو القدرات المفقودة
summary: ثبّت واستخدم حزم Codex وClaude وCursor كإضافات OpenClaw
title: حزم Plugin
x-i18n:
generated_at: "2026-04-23T07:27:35Z"
generated_at: "2026-04-23T14:00:44Z"
model: gpt-5.4
provider: openai
source_hash: 8c9e48738e059c302157dd8733178109cf34840f32a3d7b5b767ac019fbc581b
source_hash: dd5ac067546429412f8f4fd2c0da22005686c2d4377944ecd078f56054223f9b
source_path: plugins/bundles.md
workflow: 15
---
# حِزم Plugin
# حزم Plugin
يمكن لـ OpenClaw تثبيت Plugins من ثلاثة أنظمة خارجية: **Codex** و**Claude**،
و**Cursor**. تُسمى هذه **حِزم** — وهي حزم محتوى وبيانات وصفية يقوم
OpenClaw بربطها بميزات أصلية مثل skills وhooks وأدوات MCP.
يمكن لـ OpenClaw تثبيت إضافات من ثلاثة أنظمة خارجية: **Codex** و**Claude**
و**Cursor**. وتُسمى هذه **حزمًا** — وهي حزم محتوى وبيانات وصفية
يحوّلها OpenClaw إلى ميزات أصلية مثل Skills وhooks وأدوات MCP.
<Info>
الحِزم **ليست** مثل Plugins الأصلية في OpenClaw. تعمل Plugins الأصلية
داخل العملية نفسها ويمكنها تسجيل أي Capability. أما الحِزم فهي حزم محتوى مع
ربط انتقائي للميزات وحد ثقة أضيق.
لا تُعد الحزم **هي نفسها** إضافات OpenClaw الأصلية. فالإضافات الأصلية تعمل
داخل العملية ويمكنها تسجيل أي قدرة. أما الحزم فهي حزم محتوى ذات
تحويل انتقائي للميزات وحد ثقة أضيق.
</Info>
## لماذا توجد الحِزم
## لماذا توجد الحزم
تُنشر العديد من Plugins المفيدة بصيغة Codex أو Claude أو Cursor. وبدلًا
من مطالبة المؤلفين بإعادة كتابتها كـ Plugins أصلية في OpenClaw، يقوم OpenClaw
باكتشاف هذه الصيغ وربط محتواها المدعوم بمجموعة الميزات الأصلية. وهذا يعني
أنه يمكنك تثبيت حزمة أوامر Claude أو حزمة Skills من Codex
تُنشر العديد من الإضافات المفيدة بصيغة Codex أو Claude أو Cursor. وبدلًا
من مطالبة المؤلفين بإعادة كتابتها كإضافات OpenClaw أصلية، يكتشف OpenClaw
هذه الصيغ ويحوّل المحتوى المدعوم منها إلى مجموعة الميزات الأصلية. وهذا يعني
أنه يمكنك تثبيت حزمة أوامر Claude أو حزمة Skills لـ Codex
واستخدامها فورًا.
## تثبيت حزمة
<Steps>
<Step title="التثبيت من دليل أو أرشيف أو marketplace">
<Step title="التثبيت من دليل أو أرشيف أو سوق">
```bash
# دليل محلي
openclaw plugins install ./my-bundle
@ -45,7 +45,7 @@ OpenClaw بربطها بميزات أصلية مثل skills وhooks وأدوات
# أرشيف
openclaw plugins install ./my-bundle.tgz
# Claude marketplace
# سوق Claude
openclaw plugins marketplace list <marketplace-name>
openclaw plugins install <plugin-name>@<marketplace-name>
```
@ -58,65 +58,65 @@ OpenClaw بربطها بميزات أصلية مثل skills وhooks وأدوات
openclaw plugins inspect <id>
```
تظهر الحِزم كـ `Format: bundle` مع نوع فرعي `codex` أو `claude` أو `cursor`.
تظهر الحزم بالشكل `Format: bundle` مع نوع فرعي `codex` أو `claude` أو `cursor`.
</Step>
<Step title="أعد التشغيل واستخدم">
<Step title="إعادة التشغيل والاستخدام">
```bash
openclaw gateway restart
```
تصبح الميزات المربوطة (skills وhooks وأدوات MCP وإعدادات LSP الافتراضية) متاحة في الجلسة التالية.
تصبح الميزات المحوّلة (Skills وhooks وأدوات MCP وإعدادات LSP الافتراضية) متاحة في الجلسة التالية.
</Step>
</Steps>
## ما الذي يربطه OpenClaw من الحِزم
## ما الذي يحوّله OpenClaw من الحزم
ليست كل ميزة في الحزمة تعمل داخل OpenClaw اليوم. إليك ما يعمل وما
يُكتشف لكنه غير موصول بعد.
لا تعمل كل ميزات الحزم في OpenClaw حاليًا. إليك ما يعمل وما
يُكتشف لكنه لم يُوصّل بعد.
### المدعوم حاليًا
| الميزة | كيفية الربط | ينطبق على |
| ------------- | ------------------------------------------------------------------------------------------- | -------------- |
| محتوى Skills | تُحمّل جذور Skills في الحزمة كجذور Skills عادية في OpenClaw | جميع الصيغ |
| الأوامر | يُتعامل مع `commands/` و`.cursor/commands/` على أنها جذور Skills | Claude, Cursor |
| حِزم Hooks | تخطيطات `HOOK.md` + `handler.ts` بأسلوب OpenClaw | Codex |
| أدوات MCP | يُدمج تكوين MCP الخاص بالحزمة في إعدادات Pi المضمّن؛ وتُحمّل خوادم stdio وHTTP المدعومة | جميع الصيغ |
| خوادم LSP | يتم دمج `.lsp.json` من Claude و`lspServers` المعلنة في manifest في إعدادات LSP الافتراضية لـ Pi المضمّن | Claude |
| الإعدادات | يتم استيراد `settings.json` من Claude كإعدادات افتراضية لـ Pi المضمّن | Claude |
| الميزة | كيفية التحويل | ينطبق على |
| -------------- | -------------------------------------------------------------------------------------------- | -------------- |
| محتوى Skills | تُحمّل جذور Skills في الحزمة كجذور Skills عادية في OpenClaw | جميع الصيغ |
| الأوامر | يُتعامل مع `commands/` و`.cursor/commands/` على أنها جذور Skills | Claude, Cursor |
| حزم hook | تخطيطات `HOOK.md` + `handler.ts` بأسلوب OpenClaw | Codex |
| أدوات MCP | يُدمج إعداد MCP في إعدادات Pi المضمنة؛ وتُحمّل خوادم stdio وHTTP المدعومة | جميع الصيغ |
| خوادم LSP | تُدمج ملفات `.lsp.json` في Claude و`lspServers` المعلنة في البيان في إعدادات Pi LSP الافتراضية المضمنة | Claude |
| الإعدادات | يُستورد `settings.json` في Claude كإعدادات Pi مضمنة افتراضية | Claude |
#### محتوى Skills
- تُحمّل جذور Skills في الحزمة كجذور Skills عادية في OpenClaw
- تُعامل جذور `commands` في Claude على أنها جذور Skills إضافية
- تُعامل جذور `.cursor/commands` في Cursor على أنها جذور Skills إضافية
- يُتعامل مع جذور `commands` في Claude على أنها جذور Skills إضافية
- يُتعامل مع جذور `.cursor/commands` في Cursor على أنها جذور Skills إضافية
هذا يعني أن ملفات أوامر Markdown الخاصة بـ Claude تعمل عبر أداة تحميل Skills
العادية في OpenClaw. وتعمل أوامر Markdown الخاصة بـ Cursor عبر المسار نفسه.
وهذا يعني أن ملفات أوامر Markdown في Claude تعمل من خلال محمّل Skills
العادي في OpenClaw. كما تعمل أوامر Markdown في Cursor عبر المسار نفسه.
#### حِزم Hooks
#### حزم hook
- تعمل جذور hooks في الحزمة **فقط** عندما تستخدم تخطيط حزمة hooks العادي
في OpenClaw. واليوم هذه هي الحالة المتوافقة أساسًا مع Codex:
- تعمل جذور hook في الحزمة **فقط** عندما تستخدم تخطيط حزمة hook العادي
في OpenClaw. واليوم، هذه هي الحالة المتوافقة مع Codex في المقام الأول:
- `HOOK.md`
- `handler.ts` أو `handler.js`
#### MCP لـ Pi
- يمكن للحِزم المفعلة أن تساهم في تكوين خادم MCP
- يدمج OpenClaw تكوين MCP الخاص بالحزمة في إعدادات Pi المضمّن الفعالة على شكل
- يمكن للحزم المفعّلة أن تضيف إعداد خادم MCP
- يدمج OpenClaw إعداد MCP الخاص بالحزمة في إعدادات Pi المضمنة الفعلية تحت
`mcpServers`
- يكشف OpenClaw أدوات MCP المدعومة من الحزمة أثناء أدوار وكيل Pi المضمّن عبر
تشغيل خوادم stdio أو الاتصال بخوادم HTTP
- تتضمن ملفات تعريف الأدوات `coding` و`messaging` أدوات MCP الخاصة بالحزمة
- يعرّض OpenClaw أدوات MCP المدعومة من الحزمة أثناء أدوار وكيل Pi المضمن
عبر تشغيل خوادم stdio أو الاتصال بخوادم HTTP
- تتضمن ملفات تعريف الأدوات `coding` و`messaging` أدوات MCP الخاصة بالحزم
افتراضيًا؛ استخدم `tools.deny: ["bundle-mcp"]` لتعطيلها لوكيل أو Gateway
- تظل إعدادات Pi المحلية للمشروع مطبقة بعد إعدادات الحزمة الافتراضية، لذا
يمكن لإعدادات مساحة العمل تجاوز إدخالات MCP الخاصة بالحزمة عند الحاجة
- تُرتب فهارس أدوات MCP الخاصة بالحزمة ترتيبًا حتميًا قبل التسجيل، بحيث لا تؤدي
تغييرات ترتيب upstream في `listTools()` إلى اضطراب كتل أدوات prompt-cache
- لا تزال إعدادات Pi المحلية الخاصة بالمشروع تُطبّق بعد إعدادات الحزمة الافتراضية،
لذلك يمكن لإعدادات مساحة العمل تجاوز إدخالات MCP الخاصة بالحزمة عند الحاجة
- تُرتّب فهارس أدوات MCP الخاصة بالحزم ترتيبًا حتميًا قبل التسجيل، بحيث
لا تؤدي تغييرات ترتيب `listTools()` في المنبع إلى إرباك كتل أدوات prompt-cache
##### وسائل النقل
@ -157,160 +157,154 @@ OpenClaw بربطها بميزات أصلية مثل skills وhooks وأدوات
}
```
- يمكن ضبط `transport` على `"streamable-http"` أو `"sse"`؛ وعند حذفه يستخدم OpenClaw القيمة `sse`
- لا يُسمح إلا بمخططات URL من نوع `http:` و`https:`
- تدعم قيم `headers` الاستيفاء `${ENV_VAR}`
- يمكن ضبط `transport` على `"streamable-http"` أو `"sse"`؛ وعند إغفاله يستخدم OpenClaw القيمة `sse`
- يُسمح فقط بمخططات URL من نوع `http:` و`https:`
- تدعم قيم `headers` الاستيفاء بصيغة `${ENV_VAR}`
- يُرفض إدخال الخادم الذي يحتوي على كل من `command` و`url`
- تُحجب بيانات اعتماد URL ‏(userinfo ومعلمات الاستعلام) من
أوصاف الأدوات والسجلات
- يتجاوز `connectionTimeoutMs` مهلة الاتصال الافتراضية البالغة 30 ثانية
لكل من نقلي stdio وHTTP
- تُحجب بيانات اعتماد URL ‏(userinfo ومعلمات الاستعلام) من أوصاف
الأدوات والسجلات
- يتجاوز `connectionTimeoutMs` مهلة الاتصال الافتراضية البالغة 30 ثانية لكل من نقل stdio وHTTP
##### تسمية الأدوات
يسجل OpenClaw أدوات MCP الخاصة بالحزمة بأسماء آمنة للمزود بالصيغة
`serverName__toolName`. على سبيل المثال، إذا كان الخادم ذو المفتاح `"vigil-harbor"` يوفّر
الأداة `memory_search` فسيتم تسجيلها باسم `vigil-harbor__memory_search`.
يسجّل OpenClaw أدوات MCP الخاصة بالحزم بأسماء آمنة للمزوّد بالشكل
`serverName__toolName`. فعلى سبيل المثال، إذا كان الخادم بالمفتاح `"vigil-harbor"` يعرّض
الأداة `memory_search`، فستُسجَّل باسم `vigil-harbor__memory_search`.
- تُستبدل الأحرف خارج `A-Za-z0-9_-` بـ `-`
- تُحد البادئات الخاصة بالخادم عند 30 حرفًا
- تُحد أسماء الأدوات الكاملة عند 64 حرفًا
- تُقيَّد بادئات الخادم بـ 30 حرفًا كحد أقصى
- تُقيَّد أسماء الأدوات الكاملة بـ 64 حرفًا كحد أقصى
- تعود أسماء الخوادم الفارغة إلى `mcp`
- يُزال غموض الأسماء المُنقحة المتصادمة باستخدام لواحق رقمية
- يكون الترتيب النهائي المكشوف للأدوات حتميًا حسب الاسم الآمن لإبقاء
التخزين المؤقت مستقرًا عبر أدوار Pi المتكررة
- يتعامل ترشيح الملفات التعريفية مع جميع الأدوات من خادم MCP واحد في الحزمة على أنها مملوكة لـ Plugin
باسم `bundle-mcp`، لذلك يمكن أن تتضمن قوائم السماح والمنع للملفات التعريفية
إما أسماء الأدوات المكشوفة الفردية أو مفتاح Plugin باسم `bundle-mcp`
- تُفكّ الأسماء المعقّمة المتصادمة باستخدام لواحق رقمية
- يكون ترتيب الأدوات النهائي المعروض حتميًا بحسب الاسم الآمن للحفاظ على استقرار ذاكرة التخزين المؤقت في أدوار Pi المتكررة
- يتعامل ترشيح ملفات التعريف مع جميع الأدوات الصادرة من خادم MCP واحد في الحزمة على أنها مملوكة للإضافة
تحت `bundle-mcp`، لذلك يمكن لقوائم السماح والمنع في ملفات التعريف أن تتضمن إما
أسماء الأدوات المعروضة الفردية أو مفتاح الإضافة `bundle-mcp`
#### إعدادات Pi المضمّن
#### إعدادات Pi المضمنة
- يتم استيراد `settings.json` من Claude كإعدادات افتراضية لـ Pi المضمّن عندما
تكون الحزمة مفعلة
- يقوم OpenClaw بتنقية مفاتيح تجاوز shell قبل تطبيقها
- يُستورد `settings.json` في Claude كإعدادات Pi مضمنة افتراضية عندما تكون
الحزمة مفعّلة
- يعقّم OpenClaw مفاتيح تجاوز shell قبل تطبيقها
المفاتيح المنقاة:
المفاتيح المعقّمة:
- `shellPath`
- `shellCommandPrefix`
#### ‏LSP لـ Pi المضمّن
#### Pi LSP المضمن
- يمكن لحِزم Claude المفعلة أن تساهم في تكوين خادم LSP
- يحمّل OpenClaw ملف `.lsp.json` بالإضافة إلى أي مسارات `lspServers` مُعلنة في manifest
- يُدمج تكوين LSP الخاص بالحزمة في إعدادات LSP الافتراضية الفعالة لـ Pi المضمّن
- لا يمكن تشغيل اليوم إلا خوادم LSP المدعومة والمعتمدة على stdio؛ أما وسائل النقل
غير المدعومة فتظل تظهر في `openclaw plugins inspect <id>`
- يمكن لحزم Claude المفعّلة أن تضيف إعداد خادم LSP
- يحمّل OpenClaw ملف `.lsp.json` بالإضافة إلى أي مسارات `lspServers` مُعلنة في البيان
- يُدمج إعداد LSP الخاص بالحزمة في إعدادات Pi LSP الافتراضية المضمنة الفعلية
- لا يمكن تشغيل سوى خوادم LSP المدعومة المعتمدة على stdio حاليًا؛ أما وسائل النقل غير المدعومة
فتظل تظهر في `openclaw plugins inspect <id>`
### مكتشف ولكن غير منفذ
### يُكتشف ولكن لا يُنفّذ
يتم التعرف على هذه العناصر وإظهارها في التشخيصات، لكن OpenClaw لا يشغّلها:
يتم التعرّف على هذه العناصر وعرضها في أدوات التشخيص، لكن OpenClaw لا يشغّلها:
- `agents` و`hooks.json` automation و`outputStyles` الخاصة بـ Claude
- `.cursor/agents` و`.cursor/hooks.json` و`.cursor/rules` الخاصة بـ Cursor
- البيانات الوصفية المضمنة/الخاصة بالتطبيق في Codex خارج نطاق تقارير Capability
- `agents` و`hooks.json` للأتمتة و`outputStyles` في Claude
- `.cursor/agents` و`.cursor/hooks.json` و`.cursor/rules` في Cursor
- بيانات metadata المضمنة/الخاصة بالتطبيق في Codex خارج تقارير القدرات
## صيغ الحِزم
## صيغ الحزم
<AccordionGroup>
<Accordion title="حِزم Codex">
<Accordion title="حزم Codex">
العلامات: `.codex-plugin/plugin.json`
المحتوى الاختياري: `skills/` و`hooks/` و`.mcp.json` و`.app.json`
تتلاءم حِزم Codex مع OpenClaw بصورة أفضل عندما تستخدم جذور Skills و
أدلة حِزم hooks بأسلوب OpenClaw (`HOOK.md` + `handler.ts`).
تتوافق حزم Codex مع OpenClaw بأفضل شكل عندما تستخدم جذور Skills وأدلة
حزم hook بأسلوب OpenClaw (`HOOK.md` + `handler.ts`).
</Accordion>
<Accordion title="حِزم Claude">
<Accordion title="حزم Claude">
وضعا اكتشاف:
- **معتمدة على Manifest:** `.claude-plugin/plugin.json`
- **من دون Manifest:** تخطيط Claude الافتراضي (`skills/` و`commands/` و`agents/` و`hooks/` و`.mcp.json` و`.lsp.json` و`settings.json`)
- **قائم على البيان:** `.claude-plugin/plugin.json`
- **من دون بيان:** تخطيط Claude الافتراضي (`skills/` و`commands/` و`agents/` و`hooks/` و`.mcp.json` و`.lsp.json` و`settings.json`)
السلوك الخاص بـ Claude:
سلوك خاص بـ Claude:
- يُتعامل مع `commands/` على أنه محتوى Skills
- يتم استيراد `settings.json` إلى إعدادات Pi المضمّن (مع تنقية مفاتيح تجاوز shell)
- يكشف `.mcp.json` أدوات stdio المدعومة لـ Pi المضمّن
- يُحمَّل `.lsp.json` بالإضافة إلى مسارات `lspServers` المعلنة في manifest إلى إعدادات LSP الافتراضية لـ Pi المضمّن
- يتم اكتشاف `hooks/hooks.json` لكنه لا يُنفَّذ
- تكون مسارات المكونات المخصصة في manifest إضافية (فهي توسّع الإعدادات الافتراضية ولا تستبدلها)
- يُستورد `settings.json` إلى إعدادات Pi المضمنة (وتُعقّم مفاتيح تجاوز shell)
- يعرض `.mcp.json` أدوات stdio المدعومة إلى Pi المضمن
- يُحمّل `.lsp.json` بالإضافة إلى مسارات `lspServers` المُعلنة في البيان إلى إعدادات Pi LSP الافتراضية المضمنة
- يُكتشف `hooks/hooks.json` لكنه لا يُنفّذ
- تكون مسارات المكونات المخصصة في البيان إضافية (فهي توسّع القيم الافتراضية ولا تستبدلها)
</Accordion>
<Accordion title="حِزم Cursor">
<Accordion title="حزم Cursor">
العلامات: `.cursor-plugin/plugin.json`
المحتوى الاختياري: `skills/` و`.cursor/commands/` و`.cursor/agents/` و`.cursor/rules/` و`.cursor/hooks.json` و`.mcp.json`
- يُتعامل مع `.cursor/commands/` على أنه محتوى Skills
- `.cursor/rules/` و`.cursor/agents/` و`.cursor/hooks.json` للاكتشاف فقط
- تكون `.cursor/rules/` و`.cursor/agents/` و`.cursor/hooks.json` للاكتشاف فقط
</Accordion>
</AccordionGroup>
## أولوية الاكتشاف
## أسبقية الاكتشاف
يتحقق OpenClaw من صيغة Plugin الأصلية أولًا:
يفحص OpenClaw أولًا عن صيغة الإضافة الأصلية:
1. `openclaw.plugin.json` أو `package.json` صالح يحتوي على `openclaw.extensions` — يُتعامل معه كـ **Plugin أصلي**
2. علامات الحزمة (`.codex-plugin/` أو `.claude-plugin/` أو تخطيط Claude/Cursor الافتراضي) — يُتعامل معها كـ **حزمة**
1. `openclaw.plugin.json` أو `package.json` صالح يحتوي على `openclaw.extensions` — يُتعامل معه على أنه **Plugin أصلي**
2. علامات الحزمة (`.codex-plugin/` أو `.claude-plugin/` أو تخطيط Claude/Cursor الافتراضي) — يُتعامل معها على أنها **حزمة**
إذا كان الدليل يحتوي على الاثنين معًا، يستخدم OpenClaw المسار الأصلي. وهذا يمنع
تثبيت الحزم ثنائية الصيغة جزئيًا على أنها حِزم.
إذا احتوى دليل على كليهما، يستخدم OpenClaw المسار الأصلي. وهذا يمنع
تثبيت الحزم ثنائية الصيغة جزئيًا كحزم.
## تبعيات بيئة التشغيل والتنظيف
## تبعيات وقت التشغيل والتنظيف
- تُشحن تبعيات بيئة التشغيل الخاصة بالـ Plugin المضمّن داخل حزمة OpenClaw تحت
`dist/*`. لا يشغّل OpenClaw الأمر `npm install` عند بدء التشغيل من أجل Plugins
المضمّنة؛ إذ تقع على مسار الإصدار مسؤولية شحن حمولة تبعيات
كاملة للـ Plugin المضمّن (راجع قاعدة التحقق بعد النشر في
[Releasing](/ar/reference/RELEASING)).
- تتخلص تشغيلات الوكلاء الفرعيين التي تشغّل خوادم MCP المضمّنة من عملاء MCP
هؤلاء عبر مسار تنظيف بيئة التشغيل المشترك عند خروج الوكيل الفرعي، بحيث
لا تؤدي دورات حياة الوكلاء الفرعيين إلى تسرب عمليات stdio الابنة أو اتصالات
MCP الطويلة الأمد عبر الأدوار.
- تُشحَن تبعيات وقت تشغيل الإضافات المجمّعة داخل حزمة OpenClaw تحت
`dist/*`. ولا يشغّل OpenClaw الأمر `npm install` عند بدء التشغيل للإضافات
المجمّعة؛ إذ تتحمل عملية الإصدار مسؤولية شحن حمولة كاملة من
التبعيات المجمّعة (راجع قاعدة التحقق بعد النشر في
[الإصدار](/ar/reference/RELEASING)).
## الأمان
تملك الحِزم حد ثقة أضيق من Plugins الأصلية:
تمتلك الحزم حد ثقة أضيق من الإضافات الأصلية:
- لا يحمّل OpenClaw وحدات بيئة تشغيل عشوائية من الحِزم داخل العملية
- يجب أن تبقى مسارات Skills وحِزم hook داخل جذر Plugin (مع فحص الحدود)
- تتم قراءة ملفات الإعدادات بفحوصات الحدود نفسها
- قد يتم تشغيل خوادم MCP المدعومة والمعتمدة على stdio كعمليات فرعية
- لا يحمّل OpenClaw وحدات وقت تشغيل الحزم العشوائية داخل العملية
- يجب أن تبقى مسارات Skills وحزم hook داخل جذر الإضافة (مع التحقق من الحدود)
- تُقرأ ملفات الإعدادات باستخدام فحوصات الحدود نفسها
- قد تُشغَّل خوادم MCP المدعومة من نوع stdio كعمليات فرعية
وهذا يجعل الحِزم أكثر أمانًا افتراضيًا، لكن ينبغي لك مع ذلك معاملة الحِزم الخارجية
على أنها محتوى موثوق للميزات التي تكشفها.
وهذا يجعل الحزم أكثر أمانًا افتراضيًا، لكن يجب مع ذلك اعتبار الحزم الخارجية
محتوى موثوقًا بالنسبة إلى الميزات التي تعرّضها.
## استكشاف الأخطاء وإصلاحها
<AccordionGroup>
<Accordion title="يتم اكتشاف الحزمة لكن الإمكانات لا تعمل">
شغّل `openclaw plugins inspect <id>`. إذا كانت Capability مدرجة لكن مميزة على
أنها غير موصولة، فهذا حدّ في المنتج — وليس تثبيتًا معطّلًا.
<Accordion title="يتم اكتشاف الحزمة لكن القدرات لا تعمل">
شغّل `openclaw plugins inspect <id>`. إذا كانت القدرة مدرجة لكنها موسومة
على أنها غير موصولة، فهذا حدّ من حدود المنتج — وليس تثبيتًا معطوبًا.
</Accordion>
<Accordion title="ملفات أوامر Claude لا تظهر">
تأكد من أن الحزمة مفعلة وأن ملفات Markdown موجودة داخل جذر
`commands/` أو `skills/` تم اكتشافه.
<Accordion title="لا تظهر ملفات أوامر Claude">
تأكد من أن الحزمة مفعّلة وأن ملفات Markdown موجودة داخل جذر
`commands/` أو `skills/` مكتشف.
</Accordion>
<Accordion title="إعدادات Claude لا تُطبّق">
لا يُدعم إلا إعدادات Pi المضمّن القادمة من `settings.json`. ولا يتعامل OpenClaw
مع إعدادات الحزمة على أنها ترقيعات تكوين خام.
<Accordion title="لا تُطبَّق إعدادات Claude">
لا يُدعم إلا إعدادات Pi المضمنة من `settings.json`. ولا يتعامل OpenClaw
مع إعدادات الحزمة على أنها ترقيعات إعداد خام.
</Accordion>
<Accordion title="لا يتم تنفيذ hooks الخاصة بـ Claude">
`hooks/hooks.json` للاكتشاف فقط. إذا كنت تحتاج إلى hooks قابلة للتشغيل، فاستخدم
تخطيط حزمة hooks في OpenClaw أو اشحن Plugin أصليًا.
<Accordion title="لا تُنفَّذ hooks في Claude">
`hooks/hooks.json` مخصص للاكتشاف فقط. إذا كنت تحتاج إلى hooks قابلة للتشغيل، فاستخدم
تخطيط حزمة hook في OpenClaw أو اشحن Plugin أصليًا.
</Accordion>
</AccordionGroup>
## ذو صلة
- [تثبيت Plugins وتكوينها](/ar/tools/plugin)
- [بناء Plugins](/ar/plugins/building-plugins) — إنشاء Plugin أصلي
- [Plugin Manifest](/ar/plugins/manifest) — مخطط manifest الأصلي
- [تثبيت الإضافات وضبطها](/ar/tools/plugin)
- [بناء الإضافات](/ar/plugins/building-plugins) — إنشاء Plugin أصلي
- [بيان Plugin](/ar/plugins/manifest) — مخطط البيان الأصلي

285
docs/ar/plugins/codex-harness.md
View File

@ -1,32 +1,32 @@
---
read_when:
- تريد استخدام app-server harness المضمّن الخاص بـ Codex
- تحتاج إلى مراجع نماذج Codex وأمثلة إعدادات
- تريد تعطيل الرجوع الاحتياطي إلى Pi في عمليات النشر الخاصة بـ Codex فقط
summary: تشغيل دورات الوكيل المضمّن في OpenClaw عبر app-server harness المضمّن الخاص بـ Codex
- تحتاج إلى مراجع نماذج Codex وأمثلة على الإعدادات
- تريد تعطيل الرجوع إلى Pi لعمليات النشر الخاصة بـ Codex فقط
summary: شغّل أدوار الوكيل المضمّن في OpenClaw عبر app-server harness المضمّن الخاص بـ Codex
title: Codex Harness
x-i18n:
generated_at: "2026-04-23T07:27:36Z"
generated_at: "2026-04-23T14:00:37Z"
model: gpt-5.4
provider: openai
source_hash: f5eff5a2af66033d575bc05c9f31a23ed0367bedc518dc25364e60a3012bfdff
source_hash: 8172af40edb7d1f7388a606df1c8f776622ffd82b46245fb9fbd184fbf829356
source_path: plugins/codex-harness.md
workflow: 15
---
# Codex Harness
يتيح Plugin المضمّن `codex` لـ OpenClaw تشغيل دورات الوكيل المضمّن عبر
Codex app-server بدلًا من PI harness المدمج.
يتيح Plugin ‏`codex` المضمّن لـ OpenClaw تشغيل أدوار الوكيل المضمّن عبر
Codex app-server بدلًا من PI harness المضمّن.
استخدم هذا عندما تريد أن يتولى Codex جلسة الوكيل منخفضة المستوى: اكتشاف
النماذج، واستئناف الخيوط الأصلية، وCompaction الأصلي، وتنفيذ app-server.
ولا يزال OpenClaw يملك قنوات الدردشة، وملفات الجلسات، واختيار النماذج، والأدوات،
والموافقات، وتسليم الوسائط، ونسخة transcript المرئية.
النماذج، واستئناف الخيط الأصلي، وCompaction الأصلي، وتنفيذ app-server.
وما زال OpenClaw يملك قنوات الدردشة، وملفات الجلسات، واختيار النماذج، والأدوات،
والموافقات، وتسليم الوسائط، ونسخة السجل المرئية.
كما تحترم دورات Codex الأصلية أيضًا hooks المشتركة الخاصة بـ Plugin بحيث تبقى
شيفرات prompt الوسيطة، والأتمتة الواعية بـ Compaction، وmiddleware الأدوات،
ومراقبو دورة الحياة متوافقة مع PI harness:
تحترم أدوار Codex الأصلية أيضًا hooks المشتركة لـ Plugin بحيث تظل
prompt shims، والأتمتة الواعية بـ Compaction، وtool middleware، ومراقبو دورة الحياة
متوافقة مع PI harness:
- `before_prompt_build`
- `before_compaction`, `after_compaction`
@ -35,48 +35,46 @@ Codex app-server بدلًا من PI harness المدمج.
- `before_message_write`
- `agent_end`
يمكن أيضًا لـ Plugins المضمّنة تسجيل factory لامتداد Codex app-server لإضافة
middleware غير متزامن لـ `tool_result`، كما تُوجَّه كتابات transcript
المعكوسة الخاصة بـ Codex عبر `before_message_write`.
يمكن أيضًا لـ Plugins المضمّنة تسجيل Codex app-server extension factory لإضافة
`tool_result` middleware غير المتزامن.
تكون الـ harness معطلة افتراضيًا. ولا يتم اختيارها إلا عندما يكون Plugin
`codex` مفعّلًا ويكون النموذج المحلول من نوع `codex/*`، أو عندما تفرض صراحة
يكون harness معطلًا افتراضيًا. ولا يتم اختياره إلا عندما يكون Plugin ‏`codex`
مفعّلًا ويكون النموذج الذي تم حله نموذج `codex/*`، أو عندما تفرض صراحةً
`embeddedHarness.runtime: "codex"` أو `OPENCLAW_AGENT_RUNTIME=codex`.
وإذا لم تُهيئ `codex/*` مطلقًا، فإن تشغيلات PI وOpenAI وAnthropic وGemini وlocal
والمزوّدات المخصصة الحالية تبقى على سلوكها الحالي.
إذا لم تضبط `codex/*` مطلقًا، فستحتفظ تشغيلات PI وOpenAI وAnthropic وGemini وlocal
وcustom-provider الحالية بسلوكها الحالي.
## اختر بادئة النموذج الصحيحة
يمتلك OpenClaw مسارات منفصلة للوصول على هيئة OpenAI والوصول على هيئة Codex:
لدى OpenClaw مسارات منفصلة للوصول بشكل OpenAI وبشكل Codex:
| مرجع النموذج | مسار وقت التشغيل | استخدمه عندما |
| --------------------- | ------------------------------------------- | ------------- |
| `openai/gpt-5.4` | مزوّد OpenAI عبر بنية OpenClaw/PI | تريد وصولًا مباشرًا إلى OpenAI Platform API باستخدام `OPENAI_API_KEY`. |
| `openai-codex/gpt-5.4`| مزوّد OpenAI Codex OAuth عبر PI | تريد ChatGPT/Codex OAuth من دون Codex app-server harness. |
| `codex/gpt-5.4` | مزوّد Codex المضمّن بالإضافة إلى Codex harness | تريد تنفيذ Codex app-server الأصلي لدورة الوكيل المضمّن. |
| مرجع النموذج | مسار وقت التشغيل | يُستخدم عندما |
| ---------------------- | -------------------------------------------- | ----------------------------------------------------------------------- |
| `openai/gpt-5.4` | مزوّد OpenAI عبر OpenClaw/PI plumbing | تريد وصولًا مباشرًا إلى OpenAI Platform API باستخدام `OPENAI_API_KEY`. |
| `openai-codex/gpt-5.4` | مزوّد OpenAI Codex OAuth عبر PI | تريد ChatGPT/Codex OAuth من دون Codex app-server harness. |
| `codex/gpt-5.4` | مزوّد Codex المضمّن بالإضافة إلى Codex harness | تريد تنفيذ Codex app-server الأصلي لدور الوكيل المضمّن. |
لا تطالب Codex harness إلا بمراجع النماذج `codex/*`. أما المراجع الحالية `openai/*`،
و`openai-codex/*`، وAnthropic، وGemini، وxAI، وlocal، والمزوّدات المخصصة، فتبقى
لا يطالب Codex harness إلا بمراجع النماذج `codex/*`. أما مراجع `openai/*`
و`openai-codex/*` وAnthropic وGemini وxAI وlocal وcustom provider الحالية فتبقى
على مساراتها العادية.
## المتطلبات
- OpenClaw مع توافر Plugin `codex` المضمّن.
- OpenClaw مع توفر Plugin ‏`codex` المضمّن.
- Codex app-server بالإصدار `0.118.0` أو أحدث.
- توافر مصادقة Codex لعملية app-server.
- توفر مصادقة Codex لعملية app-server.
يمنع Plugin المصافحات القديمة أو غير المرقمة للإصدار الخاصة بـ app-server. وهذا يبقي
OpenClaw على سطح البروتوكول الذي تم اختباره عليه.
يحظر Plugin عمليات handshake الأقدم أو غير المرقمة لإصدار app-server. وهذا يُبقي
OpenClaw على سطح البروتوكول الذي اختُبر عليه.
بالنسبة إلى الاختبارات الحية واختبارات Docker الدخانية، تأتي المصادقة عادة من `OPENAI_API_KEY`، بالإضافة إلى
ملفات Codex CLI الاختيارية مثل `~/.codex/auth.json` و
`~/.codex/config.toml`. استخدم مواد المصادقة نفسها التي يستخدمها
Codex app-server المحلي لديك.
بالنسبة لاختبارات smoke الحية وDocker، تأتي المصادقة عادةً من `OPENAI_API_KEY`، بالإضافة
إلى ملفات Codex CLI الاختيارية مثل `~/.codex/auth.json` و
`~/.codex/config.toml`. استخدم نفس مواد المصادقة التي يستخدمها Codex app-server
المحلي لديك.
## الحد الأدنى من الإعداد
## الحد الأدنى من الإعدادات
استخدم `codex/gpt-5.4`، وفعّل Plugin المضمّن، وافرِض
Codex harness:
استخدم `codex/gpt-5.4`، ومكّن Plugin المضمّن، وافرِض harness ‏`codex`:
```json5
{
@ -99,7 +97,7 @@ Codex harness:
}
```
إذا كان config لديك يستخدم `plugins.allow`، فأدرج `codex` هناك أيضًا:
إذا كان config لديك يستخدم `plugins.allow`، فضمّن `codex` هناك أيضًا:
```json5
{
@ -114,14 +112,14 @@ Codex harness:
}
```
يؤدي ضبط `agents.defaults.model` أو نموذج وكيل إلى `codex/<model>` أيضًا إلى
تفعيل Plugin `codex` المضمّن تلقائيًا. ولا يزال إدخال Plugin الصريح
يؤدي أيضًا ضبط `agents.defaults.model` أو نموذج وكيل إلى `codex/<model>` إلى
تفعيل Plugin ‏`codex` المضمّن تلقائيًا. وما زال إدخال Plugin الصريح
مفيدًا في الإعدادات المشتركة لأنه يجعل نية النشر واضحة.
## أضف Codex من دون استبدال النماذج الأخرى
أبقِ `runtime: "auto"` عندما تريد Codex لنماذج `codex/*` وPI لكل
شيء آخر:
أبقِ `runtime: "auto"` عندما تريد استخدام Codex لنماذج `codex/*` وPI
لكل شيء آخر:
```json5
{
@ -153,7 +151,7 @@ Codex harness:
}
```
بهذا الشكل:
مع هذا الشكل:
- يستخدم `/model codex` أو `/model codex/gpt-5.4` ‏Codex app-server harness.
- يستخدم `/model gpt` أو `/model openai/gpt-5.4` مسار مزوّد OpenAI.
@ -162,7 +160,7 @@ Codex harness:
## عمليات النشر الخاصة بـ Codex فقط
عطّل الرجوع الاحتياطي إلى PI عندما تحتاج إلى إثبات أن كل دورة وكيل مضمّن تستخدم
عطّل الرجوع إلى PI عندما تحتاج إلى إثبات أن كل دور وكيل مضمّن يستخدم
Codex harness:
```json5
@ -187,14 +185,14 @@ OPENCLAW_AGENT_HARNESS_FALLBACK=none \
openclaw gateway run
```
عند تعطيل الرجوع الاحتياطي، يفشل OpenClaw مبكرًا إذا كان Plugin الخاص بـ Codex معطلًا،
أو إذا لم يكن النموذج المطلوب من نوع `codex/*`، أو إذا كان app-server قديمًا جدًا، أو إذا
مع تعطيل fallback، يفشل OpenClaw مبكرًا إذا كان Plugin ‏Codex معطلًا،
أو إذا لم يكن النموذج المطلوب مرجع `codex/*`، أو إذا كان app-server قديمًا جدًا، أو إذا
تعذر بدء app-server.
## Codex لكل وكيل
يمكنك جعل وكيل واحد خاصًا بـ Codex بينما يحتفظ الوكيل الافتراضي باختيار
تلقائي عادي:
يمكنك جعل وكيل واحد خاصًا بـ Codex فقط بينما يحتفظ الوكيل الافتراضي
بالاختيار التلقائي العادي:
```json5
{
@ -225,14 +223,14 @@ openclaw gateway run
}
```
استخدم أوامر الجلسة العادية لتبديل الوكلاء والنماذج. ينشئ `/new` جلسة
OpenClaw جديدة، وتقوم Codex harness بإنشاء أو استئناف خيط app-server
الجانبي حسب الحاجة. ويزيل `/reset` ربط جلسة OpenClaw لذلك الخيط.
استخدم أوامر الجلسة العادية للتبديل بين الوكلاء والنماذج. ينشئ `/new`
جلسة OpenClaw جديدة، وينشئ Codex harness أو يستأنف خيط app-server الجانبي
عند الحاجة. ويمسح `/reset` ربط جلسة OpenClaw لذلك الخيط.
## اكتشاف النماذج
## اكتشاف النموذج
افتراضيًا، يطلب Plugin الخاص بـ Codex النماذج المتاحة من app-server. وإذا
فشل الاكتشاف أو انتهت مهلته، يستخدم الفهرس الاحتياطي المضمّن:
افتراضيًا، يطلب Plugin ‏Codex من app-server النماذج المتاحة. إذا
فشل الاكتشاف أو انتهت مهلته، فإنه يستخدم كتالوج fallback المضمّن:
- `codex/gpt-5.4`
- `codex/gpt-5.4-mini`
@ -259,7 +257,7 @@ OpenClaw جديدة، وتقوم Codex harness بإنشاء أو استئناف
```
عطّل الاكتشاف عندما تريد أن يتجنب بدء التشغيل فحص Codex والالتزام
بالفهرس الاحتياطي:
بكتالوج fallback:
```json5
{
@ -280,7 +278,7 @@ OpenClaw جديدة، وتقوم Codex harness بإنشاء أو استئناف
## اتصال app-server والسياسة
افتراضيًا، يبدأ Plugin تشغيل Codex محليًا باستخدام:
افتراضيًا، يبدأ Plugin ‏Codex محليًا باستخدام:
```bash
codex app-server --listen stdio://
@ -289,10 +287,10 @@ codex app-server --listen stdio://
افتراضيًا، يبدأ OpenClaw جلسات Codex harness المحلية في وضع YOLO:
`approvalPolicy: "never"` و`approvalsReviewer: "user"` و
`sandbox: "danger-full-access"`. وهذه هي وضعية المشغّل المحلي الموثوق المستخدمة
لـ Heartbeat المستقلة: حيث يمكن لـ Codex استخدام أدوات shell والشبكة
من دون التوقف عند مطالبات الموافقة الأصلية التي لا يوجد أحد حاضر للإجابة عنها.
لـ Heartbeat المستقلة: إذ يمكن لـ Codex استخدام shell وأدوات الشبكة من دون
التوقف عند مطالبات الموافقة الأصلية عندما لا يكون هناك أحد للإجابة.
للاشتراك في الموافقات التي يراجعها Guardian في Codex، اضبط `appServer.mode:
للاشتراك في موافقات Codex التي يراجعها Guardian، اضبط `appServer.mode:
"guardian"`:
```json5
@ -313,7 +311,7 @@ codex app-server --listen stdio://
}
```
يوسّع وضع Guardian إلى:
يتوسع وضع Guardian إلى:
```json5
{
@ -335,24 +333,24 @@ codex app-server --listen stdio://
}
```
Guardian هو مراجع موافقات أصلي في Codex. وعندما يطلب Codex الخروج من
صندوق الحماية، أو الكتابة خارج مساحة العمل، أو إضافة أذونات مثل الوصول إلى الشبكة،
فإن Codex يوجّه طلب الموافقة ذلك إلى وكيل فرعي مراجع بدلًا من مطالبة بشرية.
ويجمع المراجع السياق ويطبق إطار المخاطر الخاص بـ Codex، ثم
يوافق أو يرفض الطلب المحدد. ويكون Guardian مفيدًا عندما تريد حواجز حماية
أكثر من وضع YOLO لكنك لا تزال تحتاج إلى وكلاء وHeartbeats غير مراقَبة
لمواصلة التقدم.
Guardian هو مراجع موافقات أصلي في Codex. عندما يطلب Codex الخروج من
sandbox، أو الكتابة خارج مساحة العمل، أو إضافة أذونات مثل الوصول إلى الشبكة،
فإن Codex يوجّه طلب الموافقة هذا إلى reviewer subagent بدلًا من مطالبة بشرية.
يجمع reviewer السياق ويطبق إطار المخاطر الخاص بـ Codex، ثم
يوافق على الطلب المحدد أو يرفضه. يكون Guardian مفيدًا عندما تريد مزيدًا من
القيود الوقائية مقارنةً بوضع YOLO لكنك ما زلت تحتاج إلى وكلاء وHeartbeat غير
مراقبة لتُحرز تقدمًا.
يتضمن Docker live harness مجسًا لـ Guardian عندما تكون
`OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1`. فهو يبدأ Codex harness في
وضع Guardian، ويتحقق من الموافقة على أمر shell مُصعّد وغير ضار، ويتحقق
من رفض رفع سر مزيف إلى وجهة خارجية غير موثوقة بحيث
يطلب الوكيل موافقة صريحة من جديد.
يتضمن Docker live harness فحص Guardian عندما تكون
`OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1`. إذ يبدأ Codex harness في
وضع Guardian، ويتحقق من الموافقة على أمر shell مصعّد وغير ضار، ويتحقق
من رفض رفع secret مزيفة إلى وجهة خارجية غير موثوقة بحيث يعود الوكيل
ليطلب موافقة صريحة.
لا تزال حقول السياسة الفردية تتغلب على `mode`، لذا يمكن لعمليات النشر المتقدمة
ما زالت حقول السياسة الفردية تتقدم على `mode`، لذا يمكن لعمليات النشر المتقدمة
مزج الإعداد المسبق مع اختيارات صريحة.
وبالنسبة إلى app-server يعمل بالفعل، استخدم نقل WebSocket:
بالنسبة إلى app-server يعمل بالفعل، استخدم نقل WebSocket:
```json5
{
@ -376,23 +374,23 @@ Guardian هو مراجع موافقات أصلي في Codex. وعندما يطل
حقول `appServer` المدعومة:
| الحقل | الافتراضي | المعنى |
| ------------------ | ---------------------------------------- | ------ |
| `transport` | `"stdio"` | يقوم `"stdio"` بتشغيل Codex؛ ويتصل `"websocket"` بـ `url`. |
| `command` | `"codex"` | الملف التنفيذي لنقل stdio. |
| `args` | `["app-server", "--listen", "stdio://"]` | الوسائط لنقل stdio. |
| `url` | غير مضبوط | عنوان URL لـ WebSocket app-server. |
| `authToken` | غير مضبوط | رمز Bearer لنقل WebSocket. |
| `headers` | `{}` | ترويسات WebSocket إضافية. |
| `requestTimeoutMs` | `60000` | المهلة الزمنية لاستدعاءات control-plane الخاصة بـ app-server. |
| `mode` | `"yolo"` | إعداد مسبق لتنفيذ YOLO أو التنفيذ الذي يراجعه guardian. |
| `approvalPolicy` | `"never"` | سياسة الموافقة الأصلية في Codex المُرسلة عند بدء/استئناف/دورة الخيط. |
| `sandbox` | `"danger-full-access"` | وضع صندوق الحماية الأصلي في Codex المُرسل عند بدء/استئناف الخيط. |
| `approvalsReviewer`| `"user"` | استخدم `"guardian_subagent"` للسماح لـ Codex Guardian بمراجعة المطالبات. |
| `serviceTier` | غير مضبوط | طبقة خدمة اختيارية لـ Codex app-server: `"fast"` أو `"flex"` أو `null`. ويتم تجاهل القيم القديمة غير الصالحة. |
| الحقل | الافتراضي | المعنى |
| ------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `transport` | `"stdio"` | تقوم `"stdio"` بتشغيل Codex؛ وتتصل `"websocket"` بـ `url`. |
| `command` | `"codex"` | الملف التنفيذي لنقل stdio. |
| `args` | `["app-server", "--listen", "stdio://"]` | الوسيطات لنقل stdio. |
| `url` | غير مضبوط | عنوان URL لـ WebSocket app-server. |
| `authToken` | غير مضبوط | Bearer token لنقل WebSocket. |
| `headers` | `{}` | ترويسات WebSocket إضافية. |
| `requestTimeoutMs` | `60000` | المهلة الزمنية لاستدعاءات control-plane الخاصة بـ app-server. |
| `mode` | `"yolo"` | إعداد مسبق لتنفيذ YOLO أو التنفيذ بمراجعة Guardian. |
| `approvalPolicy` | `"never"` | سياسة الموافقة الأصلية في Codex المرسلة إلى بدء/استئناف/دور الخيط. |
| `sandbox` | `"danger-full-access"` | وضع sandbox الأصلي في Codex المرسل إلى بدء/استئناف الخيط. |
| `approvalsReviewer` | `"user"` | استخدم `"guardian_subagent"` للسماح لـ Codex Guardian بمراجعة المطالبات. |
| `serviceTier` | غير مضبوط | مستوى خدمة Codex app-server اختياري: `"fast"` أو `"flex"` أو `null`. يتم تجاهل القيم القديمة غير الصالحة. |
لا تزال متغيرات البيئة الأقدم تعمل كقيم احتياطية للاختبار المحلي عندما
يكون حقل الإعداد المطابق غير مضبوط:
ما زالت متغيرات البيئة الأقدم تعمل كبدائل احتياطية للاختبار المحلي عندما
يكون حقل config المطابق غير مضبوط:
- `OPENCLAW_CODEX_APP_SERVER_BIN`
- `OPENCLAW_CODEX_APP_SERVER_ARGS`
@ -402,9 +400,9 @@ Guardian هو مراجع موافقات أصلي في Codex. وعندما يطل
تمت إزالة `OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1`. استخدم
`plugins.entries.codex.config.appServer.mode: "guardian"` بدلًا من ذلك، أو
`OPENCLAW_CODEX_APP_SERVER_MODE=guardian` لاختبار محلي لمرة واحدة. ويُفضَّل config
لعمليات النشر القابلة لإعادة التكرار لأنه يُبقي سلوك Plugin في
الملف المُراجَع نفسه مع بقية إعداد Codex harness.
`OPENCLAW_CODEX_APP_SERVER_MODE=guardian` لاختبار محلي لمرة واحدة. يُفضَّل config
لعمليات النشر القابلة للتكرار لأنه يبقي سلوك Plugin في
نفس الملف المُراجع مع بقية إعداد Codex harness.
## وصفات شائعة
@ -422,7 +420,7 @@ Codex محلي مع نقل stdio الافتراضي:
}
```
التحقق من Codex-only harness، مع تعطيل الرجوع الاحتياطي إلى PI:
التحقق من Codex-only harness، مع تعطيل الرجوع إلى PI:
```json5
{
@ -439,7 +437,7 @@ Codex محلي مع نقل stdio الافتراضي:
}
```
موافقات Codex التي يراجعها Guardian:
موافقات Codex بمراجعة Guardian:
```json5
{
@ -484,91 +482,90 @@ app-server بعيد مع ترويسات صريحة:
}
```
يبقى تبديل النماذج تحت تحكم OpenClaw. وعندما تُرفق جلسة OpenClaw
بخيط Codex موجود، ترسل الدورة التالية
النموذج الحالي المحدد من نوع `codex/*`، والمزوّد، وسياسة الموافقة، وصندوق الحماية، وطبقة الخدمة إلى
app-server مرة أخرى. ويُبقي التبديل من `codex/gpt-5.4` إلى `codex/gpt-5.2`
ربط الخيط، لكنه يطلب من Codex المتابعة باستخدام النموذج المحدد حديثًا.
يظل تبديل النماذج خاضعًا لتحكم OpenClaw. عندما تكون جلسة OpenClaw مرفقة
بخيط Codex موجود، يرسل الدور التالي
النموذج `codex/*` المحدد حاليًا، والمزوّد، وسياسة الموافقة، وsandbox، ومستوى الخدمة إلى
app-server مرة أخرى. يحافظ التبديل من `codex/gpt-5.4` إلى `codex/gpt-5.2`
على ربط الخيط لكنه يطلب من Codex المتابعة باستخدام النموذج المحدد حديثًا.
## أمر Codex
يسجل Plugin المضمّن الأمر `/codex` كأمر slash مخوّل. وهو
عام ويعمل على أي قناة تدعم أوامر OpenClaw النصية.
الأشكال الشائعة:
الصيغ الشائعة:
- يعرض `/codex status` اتصال app-server المباشر، والنماذج، والحساب، وحدود المعدل، وخوادم MCP، وSkills.
- يسرد `/codex models` نماذج Codex app-server المباشرة.
- يسرد `/codex threads [filter]` خيوط Codex الحديثة.
- يعرض `/codex status` حالة اتصال app-server الحية، والنماذج، والحساب، وحدود المعدل، وخوادم MCP، وSkills.
- يعرض `/codex models` نماذج Codex app-server الحية.
- يعرض `/codex threads [filter]` خيوط Codex الحديثة.
- يربط `/codex resume <thread-id>` جلسة OpenClaw الحالية بخيط Codex موجود.
- يطلب `/codex compact` من Codex app-server تنفيذ Compaction للخيط المرتبط.
- يبدأ `/codex review` مراجعة Codex الأصلية للخيط المرتبط.
- يطلب `/codex compact` من Codex app-server تنفيذ Compaction للخيط المرفق.
- يبدأ `/codex review` مراجعة Codex الأصلية للخيط المرفق.
- يعرض `/codex account` حالة الحساب وحدود المعدل.
- يسرد `/codex mcp` حالة خادم MCP في Codex app-server.
- يسرد `/codex skills` Skills في Codex app-server.
- يعرض `/codex mcp` حالة خادم MCP في Codex app-server.
- يعرض `/codex skills` Skills الخاصة بـ Codex app-server.
يكتب `/codex resume` ملف الربط الجانبي نفسه الذي تستخدمه harness في
الدورات العادية. وفي الرسالة التالية، يستأنف OpenClaw خيط Codex ذلك، ويمرر
نموذج OpenClaw الحالي المحدد من نوع `codex/*` إلى app-server، ويحافظ على
تفعيل السجل الموسع.
يكتب `/codex resume` ملف الربط الجانبي نفسه الذي يستخدمه harness في
الأدوار العادية. وفي الرسالة التالية، يستأنف OpenClaw خيط Codex هذا، ويمرر
نموذج OpenClaw ‏`codex/*` المحدد حاليًا إلى app-server، ويبقي
السجل الموسّع مفعّلًا.
يتطلب سطح الأوامر Codex app-server بالإصدار `0.118.0` أو أحدث. وتُبلَّغ الطرق
التحكمية الفردية على أنها `unsupported by this Codex app-server` إذا كان
app-server مستقبليًا أو مخصصًا لا يوفّر طريقة JSON-RPC تلك.
يتطلب سطح الأوامر Codex app-server بالإصدار `0.118.0` أو أحدث. وتُبلَّغ
طرق التحكم الفردية على أنها `unsupported by this Codex app-server` إذا كان
app-server مستقبليًا أو مخصصًا لا يعرّض طريقة JSON-RPC تلك.
## الأدوات والوسائط وCompaction
تغيّر Codex harness منفّذ الوكيل المضمّن منخفض المستوى فقط.
لا يغيّر Codex harness سوى منفذ الوكيل المضمّن منخفض المستوى.
ولا يزال OpenClaw يبني قائمة الأدوات ويتلقى نتائج الأدوات الديناميكية من
harness. ويستمر النص والصور والفيديو والموسيقى وTTS والموافقات ومخرجات
أدوات المراسلة عبر مسار التسليم العادي في OpenClaw.
وما زال OpenClaw يبني قائمة الأدوات ويتلقى نتائج الأدوات الديناميكية من
harness. ويستمر النص، والصور، والفيديو، والموسيقى، وTTS، والموافقات، ومخرجات
أداة المراسلة عبر مسار التسليم العادي في OpenClaw.
تُوجَّه طلبات موافقة أدوات Codex MCP عبر تدفق موافقة Plugin في OpenClaw
عندما يضع Codex العلامة `_meta.codex_approval_kind` على
`"mcp_tool_call"`؛ أما طلبات الاستحضار الأخرى وطلبات الإدخال الحر فلا تزال
تُوجَّه طلبات موافقة أداة Codex MCP عبر تدفق موافقة Plugin في OpenClaw
عندما يضع Codex القيمة `_meta.codex_approval_kind` على
`"mcp_tool_call"`؛ أما طلبات elicitation الأخرى وطلبات الإدخال الحر فما زالت
تفشل بشكل مغلق.
عندما يستخدم النموذج المحدد Codex harness، يُفوَّض Compaction الأصلي للخيط إلى
Codex app-server. ويحتفظ OpenClaw بنسخة transcript معكوسة من أجل سجل القناة،
عندما يستخدم النموذج المحدد Codex harness، يتم تفويض Compaction الأصلي للخيط إلى
Codex app-server. يحتفظ OpenClaw بنسخة مرآة من السجل من أجل سجل القناة،
والبحث، و`/new`، و`/reset`، والتبديل المستقبلي للنموذج أو harness. وتتضمن
النسخة المعكوسة مطالبة المستخدم، والنص النهائي للمساعد، وسجلات استدلال أو خطة
خفيفة من Codex عندما يصدرها app-server. وحتى الآن، يسجل OpenClaw فقط
إشارات بدء Compaction الأصلي واكتماله. وهو لا يعرّض بعد ملخصًا مقروءًا للبشر
عن Compaction أو قائمة قابلة للتدقيق بالعناصر التي احتفظ بها Codex بعد Compaction.
النسخة المرآة مطالبة المستخدم، والنص النهائي للمساعد، وسجلات reasoning أو الخطة الخفيفة من Codex
عندما يصدرها app-server. وحتى اليوم، لا يسجل OpenClaw إلا إشارات
بدء Compaction الأصلي واكتماله. وهو لا يعرّض بعد ملخصًا مقروءًا بشريًا لـ
Compaction أو قائمة قابلة للتدقيق بالعناصر التي احتفظ بها Codex بعد Compaction.
لا يتطلب توليد الوسائط وجود PI. إذ تستمر الصور والفيديو والموسيقى وPDF وTTS و
فهم الوسائط في استخدام إعدادات المزوّد/النموذج المطابقة مثل
لا يتطلب إنشاء الوسائط PI. إذ تستمر عمليات الصور، والفيديو، والموسيقى، وPDF، وTTS، وفهم الوسائط
في استخدام إعدادات المزوّد/النموذج المطابقة مثل
`agents.defaults.imageGenerationModel` و`videoGenerationModel` و`pdfModel` و
`messages.tts`.
## استكشاف الأخطاء وإصلاحها
**لا يظهر Codex في `/model`:** فعّل `plugins.entries.codex.enabled`،
واضبط مرجع نموذج `codex/*`، أو تحقّق مما إذا كان `plugins.allow` يستبعد `codex`.
واضبط مرجع نموذج `codex/*`، أو تحقّق مما إذا كانت `plugins.allow` تستبعد `codex`.
**يستخدم OpenClaw PI بدلًا من Codex:** إذا لم تطالب أي Codex harness بالتشغيل،
فقد يستخدم OpenClaw PI كخلفية توافقية. اضبط
**يستخدم OpenClaw ‏PI بدلًا من Codex:** إذا لم يطالب أي Codex harness بالتشغيل،
فقد يستخدم OpenClaw ‏PI كواجهة توافق. اضبط
`embeddedHarness.runtime: "codex"` لفرض اختيار Codex أثناء الاختبار، أو
`embeddedHarness.fallback: "none"` للفشل عندما لا تطابق أي Plugin harness. وبمجرد
اختيار Codex app-server، تظهر إخفاقاته مباشرة من دون إعدادات
رجوع احتياطي إضافية.
`embeddedHarness.fallback: "none"` للفشل عند عدم تطابق أي Plugin harness. وبمجرد
اختيار Codex app-server، تظهر إخفاقاته مباشرةً من دون إعداد fallback إضافي.
**تم رفض app-server:** قم بترقية Codex بحيث تُبلّغ مصافحة app-server
**تم رفض app-server:** رقِّ Codex لكي تبلغ عملية handshake الخاصة بـ app-server
عن الإصدار `0.118.0` أو أحدث.
**اكتشاف النموذج بطيء:** خفّض `plugins.entries.codex.config.discovery.timeoutMs`
أو عطّل الاكتشاف.
**يفشل نقل WebSocket فورًا:** تحقّق من `appServer.url` و`authToken`
ومن أن app-server البعيد يتحدث الإصدار نفسه من بروتوكول Codex app-server.
**يفشل نقل WebSocket فورًا:** تحقّق من `appServer.url` و`authToken`،
ومن أن app-server البعيد يتحدث بنفس إصدار بروتوكول Codex app-server.
**يستخدم نموذج غير Codex PI:** هذا متوقع. إذ لا تطالب Codex harness إلا
**يستخدم نموذج غير Codex ‏PI:** هذا متوقع. لا يطالب Codex harness إلا
بمراجع النماذج `codex/*`.
## ذو صلة
- [Plugins الخاصة بـ Agent Harness](/ar/plugins/sdk-agent-harness)
- [مزوّدو النماذج](/ar/concepts/model-providers)
- [Plugins Agent Harness](/ar/plugins/sdk-agent-harness)
- [مزودو النماذج](/ar/concepts/model-providers)
- [مرجع الإعدادات](/ar/gateway/configuration-reference)
- [الاختبار](/ar/help/testing#live-codex-app-server-harness-smoke)

658
docs/ar/plugins/manifest.md
View File

@ -1,79 +1,76 @@
---
read_when:
- أنت تبني Plugin لـ OpenClaw
- تحتاج إلى شحن مخطط تكوين للـ Plugin أو تصحيح أخطاء التحقق من Plugin
summary: Manifest الخاص بالـ Plugin + متطلبات مخطط JSON (تحقق صارم من التكوين)
title: Manifest الخاص بالـ Plugin
- تحتاج إلى شحن مخطط تكوين للـ Plugin أو تصحيح أخطاء التحقق من صحة الـ Plugin
summary: متطلبات بيان Plugin + مخطط JSON ‏(تحقق صارم من التكوين)
title: بيان Plugin
x-i18n:
generated_at: "2026-04-23T07:28:05Z"
generated_at: "2026-04-23T14:01:07Z"
model: gpt-5.4
provider: openai
source_hash: de71b9d556c2696d3279f202b66d57aa8014e9c89d81e3f453602744120d1675
source_hash: d48810f604aa0c3ff8553528cfa4cb735d1d5e7a15b1bbca6152070d6c8f9cce
source_path: plugins/manifest.md
workflow: 15
---
# Manifest الخاص بالـ Plugin (`openclaw.plugin.json`)
# بيان Plugin ‏(`openclaw.plugin.json`)
هذه الصفحة مخصصة فقط لـ **Manifest Plugin الأصلي في OpenClaw**.
هذه الصفحة مخصصة لـ **بيان Plugin الأصلي في OpenClaw** فقط.
بالنسبة إلى تخطيطات الحزم المتوافقة، راجع [حزم Plugin](/ar/plugins/bundles).
للتعرف على تخطيطات الحزم المتوافقة، راجع [حزم Plugin](/ar/plugins/bundles).
تستخدم تنسيقات الحزم المتوافقة ملفات Manifest مختلفة:
تستخدم تنسيقات الحزم المتوافقة ملفات بيان مختلفة:
- حزمة Codex: `.codex-plugin/plugin.json`
- حزمة Claude: `.claude-plugin/plugin.json` أو تخطيط مكوّن Claude الافتراضي
بدون Manifest
- حزمة Cursor: `.cursor-plugin/plugin.json`
- حزمة Codex: ‏`.codex-plugin/plugin.json`
- حزمة Claude: ‏`.claude-plugin/plugin.json` أو تخطيط مكونات Claude
الافتراضي بدون بيان
- حزمة Cursor: ‏`.cursor-plugin/plugin.json`
يكتشف OpenClaw هذه التخطيطات المتوافقة للحزم تلقائيًا أيضًا، لكنه لا يتحقق منها
مقابل مخطط `openclaw.plugin.json` الموصوف هنا.
يكتشف OpenClaw تخطيطات الحزم هذه تلقائيًا أيضًا، لكنها لا تخضع للتحقق
مقابل مخطط `openclaw.plugin.json` الموضح هنا.
بالنسبة إلى الحزم المتوافقة، يقرأ OpenClaw حاليًا بيانات الحزمة الوصفية بالإضافة إلى
جذور Skills المعلنة، وجذور أوامر Claude، وقيم Claude bundle الافتراضية في `settings.json`،
وقيم Claude bundle الافتراضية في LSP، وحزم hooks المدعومة عندما يطابق التخطيط
بالنسبة إلى الحزم المتوافقة، يقرأ OpenClaw حاليًا بيانات تعريف الحزمة إضافةً إلى
جذور Skills المعلنة، وجذور أوامر Claude، والقيم الافتراضية في `settings.json` لحزمة Claude،
وقيم LSP الافتراضية لحزمة Claude، ومجموعات hooks المدعومة عندما يطابق التخطيط
توقعات وقت تشغيل OpenClaw.
يجب على كل Plugin أصلي في OpenClaw **أن يرفق** ملف `openclaw.plugin.json` في
**جذر Plugin**. يستخدم OpenClaw هذا الـ Manifest للتحقق من التكوين
**من دون تنفيذ كود Plugin**. وتُعامل الملفات المفقودة أو غير الصالحة على أنها
أخطاء Plugin وتمنع التحقق من التكوين.
**يجب** أن يشحن كل Plugin أصلي في OpenClaw ملف `openclaw.plugin.json` داخل
**جذر Plugin**. يستخدم OpenClaw هذا البيان للتحقق من التكوين
**من دون تنفيذ كود Plugin**. وتُعامل البيانات المفقودة أو غير الصالحة على أنها
أخطاء في Plugin وتمنع التحقق من التكوين.
راجع دليل نظام Plugins الكامل: [Plugins](/ar/tools/plugin).
وللاطلاع على نموذج القدرات الأصلي وإرشادات التوافق الخارجي الحالية:
راجع دليل نظام Plugin الكامل: [Plugins](/ar/tools/plugin).
وللاطلاع على نموذج القدرات الأصلي والإرشادات الحالية للتوافق الخارجي:
[نموذج القدرات](/ar/plugins/architecture#public-capability-model).
## ما الذي يفعله هذا الملف
إن `openclaw.plugin.json` هو البيانات الوصفية التي يقرأها OpenClaw قبل أن يحمّل
يمثل `openclaw.plugin.json` بيانات التعريف التي يقرأها OpenClaw قبل أن يحمّل
كود Plugin الخاص بك.
استخدمه من أجل:
- هوية Plugin
- التحقق من التكوين
- بيانات المصادقة والإعداد الأولي الوصفية التي يجب أن تكون متاحة من دون تشغيل
وقت تشغيل Plugin
- تلميحات تفعيل منخفضة الكلفة يمكن لأسطح طبقة التحكم فحصها قبل تحميل وقت التشغيل
- واصفات إعداد منخفضة الكلفة يمكن لأسطح الإعداد/الإعداد الأولي فحصها قبل
تحميل وقت التشغيل
- بيانات الأسماء المستعارة والتفعيل التلقائي التي ينبغي حلها قبل تحميل وقت تشغيل Plugin
- بيانات مختصرة لملكية عائلات النماذج ينبغي أن تفعّل
Plugin تلقائيًا قبل تحميل وقت التشغيل
- لقطات ثابتة لملكية القدرات تُستخدم في توصيل التوافق المضمّن وتغطية العقود
- بيانات وصفية منخفضة الكلفة لمشغل QA يمكن لمضيف `openclaw qa` المشترك فحصها
- بيانات تعريف المصادقة والإعداد الأولي التي يجب أن تكون متاحة من دون تشغيل وقت تشغيل Plugin
- تلميحات تنشيط منخفضة الكلفة يمكن لواجهات طبقة التحكم فحصها قبل تحميل وقت التشغيل
- واصفات إعداد منخفضة الكلفة يمكن لواجهات الإعداد/التهيئة الأولى فحصها قبل تحميل وقت التشغيل
- بيانات تعريف الأسماء المستعارة والتمكين التلقائي التي يجب حسمها قبل تحميل وقت تشغيل Plugin
- بيانات تعريف مختصرة لملكية عائلات النماذج التي يجب أن تفعّل Plugin تلقائيًا قبل تحميل وقت التشغيل
- لقطات ثابتة لملكية القدرات تُستخدم في أسلاك التوافق المجمعة وتغطية العقود
- بيانات تعريف منخفضة الكلفة لمشغل QA يمكن لمضيف `openclaw qa` المشترك فحصها
قبل تحميل وقت تشغيل Plugin
- بيانات وصفية خاصة بتكوين القناة ينبغي دمجها في
أسطح الكتالوج والتحقق من دون تحميل وقت التشغيل
- hints لواجهة التكوين
- بيانات تعريف تكوين خاصة بالقنوات يجب دمجها في الكتالوج وواجهات التحقق
من دون تحميل وقت التشغيل
- تلميحات واجهة مستخدم للتكوين
لا تستخدمه من أجل:
- تسجيل سلوك وقت التشغيل
- إعلان نقاط دخول الكود
- بيانات تثبيت npm الوصفية
- التصريح بنقاط دخول الكود
- بيانات تعريف تثبيت npm
فهذه تنتمي إلى كود Plugin الخاص بك وإلى `package.json`.
هذه الأشياء تنتمي إلى كود Plugin الخاص بك و`package.json`.
## مثال أدنى
@ -94,7 +91,7 @@ x-i18n:
{
"id": "openrouter",
"name": "OpenRouter",
"description": "Plugin provider لـ OpenRouter",
"description": "OpenRouter provider plugin",
"version": "1.0.0",
"providers": ["openrouter"],
"modelSupport": {
@ -153,67 +150,67 @@ x-i18n:
## مرجع الحقول ذات المستوى الأعلى
| الحقل | مطلوب | النوع | المعنى |
| ------------------------------------ | -------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | نعم | `string` | معرّف Plugin القانوني. وهو المعرّف المستخدم في `plugins.entries.<id>`. |
| `configSchema` | نعم | `object` | مخطط JSON مضمّن لتكوين هذا الـ Plugin. |
| `enabledByDefault` | لا | `true` | يضع علامة على أن Plugin المضمّن مفعّل افتراضيًا. احذفه، أو اضبط أي قيمة غير `true`، لترك Plugin معطّلًا افتراضيًا. |
| `legacyPluginIds` | لا | `string[]` | معرّفات قديمة تُطبَّع إلى معرّف Plugin القانوني هذا. |
| `autoEnableWhenConfiguredProviders` | لا | `string[]` | معرّفات provider التي يجب أن تفعّل هذا الـ Plugin تلقائيًا عندما تشير إليها المصادقة أو التكوين أو مراجع النماذج. |
| `kind` | لا | `"memory"` \| `"context-engine"` | يعلن نوع Plugin حصريًا يُستخدم بواسطة `plugins.slots.*`. |
| `channels` | لا | `string[]` | معرّفات القنوات التي يملكها هذا الـ Plugin. تُستخدم للاكتشاف والتحقق من التكوين. |
| `providers` | لا | `string[]` | معرّفات provider التي يملكها هذا الـ Plugin. |
| `modelSupport` | لا | `object` | بيانات وصفية مختصرة لعائلات النماذج يملكها الـ Manifest وتُستخدم لتحميل Plugin تلقائيًا قبل وقت التشغيل. |
| `providerEndpoints` | لا | `object[]` | بيانات وصفية يملكها الـ Manifest لمضيف endpoint/baseUrl لمسارات provider والتي يجب على core تصنيفها قبل تحميل وقت تشغيل provider. |
| `cliBackends` | لا | `string[]` | معرّفات backend الخاصة بالاستدلال عبر CLI التي يملكها هذا الـ Plugin. تُستخدم للتفعيل التلقائي عند بدء التشغيل من مراجع التكوين الصريحة. |
| `syntheticAuthRefs` | لا | `string[]` | مراجع provider أو backend CLI التي يجب فحص hook المصادقة الاصطناعي المملوك للـ Plugin الخاص بها أثناء اكتشاف النماذج البارد قبل تحميل وقت التشغيل. |
| `nonSecretAuthMarkers` | لا | `string[]` | قيم API key نائبة يملكها Plugin المضمّن وتمثل حالة اعتماد محلية أو OAuth أو اعتماد بيئي غير سرية. |
| `commandAliases` | لا | `object[]` | أسماء الأوامر التي يملكها هذا الـ Plugin والتي يجب أن تنتج تشخيصات تكوين وCLI مدركة للـ Plugin قبل تحميل وقت التشغيل. |
| `providerAuthEnvVars` | لا | `Record<string, string[]>` | بيانات وصفية رخيصة لمصادقة provider عبر env يمكن لـ OpenClaw فحصها من دون تحميل كود Plugin. |
| `providerAuthAliases` | لا | `Record<string, string>` | معرّفات provider التي يجب أن تعيد استخدام معرّف provider آخر للبحث عن المصادقة، مثل provider خاص بالبرمجة يشارك API key وملفات تعريف المصادقة الخاصة بالـ provider الأساسي. |
| `channelEnvVars` | لا | `Record<string, string[]>` | بيانات وصفية رخيصة للقناة عبر env يمكن لـ OpenClaw فحصها من دون تحميل كود Plugin. استخدم هذا من أجل إعداد القناة أو أسطح المصادقة المعتمدة على env التي يجب أن تراها مساعدات بدء التشغيل/التكوين العامة. |
| `providerAuthChoices` | لا | `object[]` | بيانات وصفية رخيصة لاختيارات المصادقة من أجل منتقيات الإعداد الأولي، وحل provider المفضل، وربط إشارات CLI البسيط. |
| `activation` | لا | `object` | تلميحات تفعيل رخيصة للتحميل المحفَّز بواسطة provider أو command أو channel أو route أو capability. بيانات وصفية فقط؛ وما يزال وقت تشغيل Plugin يملك السلوك الفعلي. |
| `setup` | لا | `object` | واصفات إعداد/إعداد أولي رخيصة يمكن لأسطح الاكتشاف والإعداد فحصها من دون تحميل وقت تشغيل Plugin. |
| `qaRunners` | لا | `object[]` | واصفات رخيصة لمشغلات QA يستخدمها مضيف `openclaw qa` المشترك قبل تحميل وقت تشغيل Plugin. |
| `contracts` | لا | `object` | لقطة ثابتة للقدرات المضمّنة من أجل hooks المصادقة الخارجية، والكلام، والنسخ الفوري، والصوت الفوري، وفهم الوسائط، وتوليد الصور، وتوليد الموسيقى، وتوليد الفيديو، وجلب الويب، والبحث في الويب، وملكية الأدوات. |
| `mediaUnderstandingProviderMetadata` | لا | `Record<string, object>` | قيم افتراضية رخيصة لفهم الوسائط لمعرّفات provider المعلنة في `contracts.mediaUnderstandingProviders`. |
| `channelConfigs` | لا | `Record<string, object>` | بيانات وصفية لتكوين القناة يملكها الـ Manifest وتُدمج في أسطح الاكتشاف والتحقق قبل تحميل وقت التشغيل. |
| `skills` | لا | `string[]` | دلائل Skills المطلوب تحميلها، نسبةً إلى جذر Plugin. |
| `name` | لا | `string` | اسم Plugin قابل للقراءة البشرية. |
| `description` | لا | `string` | ملخص قصير يظهر في أسطح Plugin. |
| `version` | لا | `string` | إصدار Plugin لأغراض معلوماتية. |
| `uiHints` | لا | `Record<string, object>` | تسميات UI، وعناصر نائبة، وتلميحات الحساسية لحقول التكوين. |
| الحقل | مطلوب | النوع | المعنى |
| ------------------------------------ | ------ | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | نعم | `string` | معرّف Plugin الأساسي. هذا هو المعرّف المستخدم في `plugins.entries.<id>`. |
| `configSchema` | نعم | `object` | مخطط JSON مضمّن لتكوين هذا Plugin. |
| `enabledByDefault` | لا | `true` | يحدد أن Plugin المضمّن مفعّل افتراضيًا. احذفه، أو عيّن أي قيمة غير `true`، لترك Plugin معطّلًا افتراضيًا. |
| `legacyPluginIds` | لا | `string[]` | معرّفات قديمة تتم تسويتها إلى معرّف Plugin الأساسي هذا. |
| `autoEnableWhenConfiguredProviders` | لا | `string[]` | معرّفات Providers التي يجب أن تفعّل هذا Plugin تلقائيًا عندما تشير إليها المصادقة أو التكوين أو مراجع النماذج. |
| `kind` | لا | `"memory"` \| `"context-engine"` | يصرّح بنوع Plugin حصري يُستخدم بواسطة `plugins.slots.*`. |
| `channels` | لا | `string[]` | معرّفات القنوات التي يملكها هذا Plugin. تُستخدم للاكتشاف والتحقق من التكوين. |
| `providers` | لا | `string[]` | معرّفات Providers التي يملكها هذا Plugin. |
| `modelSupport` | لا | `object` | بيانات تعريف مختصرة مملوكة للبيان لعائلات النماذج وتُستخدم لتحميل Plugin تلقائيًا قبل وقت التشغيل. |
| `providerEndpoints` | لا | `object[]` | بيانات تعريف endpoint مملوكة للبيان بشأن `host`/`baseUrl` لمسارات Providers التي يجب على النواة تصنيفها قبل تحميل وقت تشغيل Provider. |
| `cliBackends` | لا | `string[]` | معرّفات واجهات CLI الخلفية للاستدلال التي يملكها هذا Plugin. تُستخدم للتنشيط التلقائي عند بدء التشغيل من مراجع التكوين الصريحة. |
| `syntheticAuthRefs` | لا | `string[]` | مراجع Provider أو CLI backend التي يجب فحص hook المصادقة الاصطناعية المملوك للـ Plugin لها أثناء اكتشاف النماذج البارد قبل تحميل وقت التشغيل. |
| `nonSecretAuthMarkers` | لا | `string[]` | قيم placeholder لمفاتيح API مملوكة لـ Plugin مضمّن وتمثل حالة اعتماد محلية أو OAuth أو اعتمادًا محيطيًا غير سري. |
| `commandAliases` | لا | `object[]` | أسماء الأوامر التي يملكها هذا Plugin ويجب أن تنتج تشخيصات واعية بالـ Plugin للتكوين وCLI قبل تحميل وقت التشغيل. |
| `providerAuthEnvVars` | لا | `Record<string, string[]>` | بيانات تعريف منخفضة الكلفة لمتغيرات بيئة مصادقة Provider يمكن لـ OpenClaw فحصها من دون تحميل كود Plugin. |
| `providerAuthAliases` | لا | `Record<string, string>` | معرّفات Providers التي يجب أن تعيد استخدام معرّف Provider آخر للبحث عن المصادقة، مثل Provider برمجي يشارك مفتاح API وملفات تعريف المصادقة مع Provider الأساسي. |
| `channelEnvVars` | لا | `Record<string, string[]>` | بيانات تعريف منخفضة الكلفة لمتغيرات بيئة القناة يمكن لـ OpenClaw فحصها من دون تحميل كود Plugin. استخدم هذا لإعداد القنوات أو أسطح المصادقة المعتمدة على env التي يجب أن تراها مساعدات بدء التشغيل/التكوين العامة. |
| `providerAuthChoices` | لا | `object[]` | بيانات تعريف منخفضة الكلفة لاختيارات المصادقة لمنتقيات الإعداد الأولي، وحل Providers المفضلة، وربط إشارات CLI البسيطة. |
| `activation` | لا | `object` | تلميحات تنشيط منخفضة الكلفة للتحميل المرتبط بالـ Provider أو الأمر أو القناة أو المسار أو القدرة. بيانات تعريف فقط؛ أما وقت تشغيل Plugin فلا يزال يملك السلوك الفعلي. |
| `setup` | لا | `object` | واصفات إعداد/تهيئة أولية منخفضة الكلفة يمكن لواجهات الاكتشاف والإعداد فحصها من دون تحميل وقت تشغيل Plugin. |
| `qaRunners` | لا | `object[]` | واصفات منخفضة الكلفة لمشغلات QA يستخدمها مضيف `openclaw qa` المشترك قبل تحميل وقت تشغيل Plugin. |
| `contracts` | لا | `object` | لقطة ثابتة للقدرات المجمعة للمصادقة الخارجية، والكلام، والنسخ الفوري، والصوت الفوري، وفهم الوسائط، وتوليد الصور، وتوليد الموسيقى، وتوليد الفيديو، وجلب الويب، والبحث في الويب، وملكية الأدوات. |
| `mediaUnderstandingProviderMetadata` | لا | `Record<string, object>` | إعدادات افتراضية منخفضة الكلفة لفهم الوسائط لمعرّفات Providers المصرّح بها في `contracts.mediaUnderstandingProviders`. |
| `channelConfigs` | لا | `Record<string, object>` | بيانات تعريف تكوين قناة مملوكة للبيان تُدمج في أسطح الاكتشاف والتحقق قبل تحميل وقت التشغيل. |
| `skills` | لا | `string[]` | أدلة Skills المطلوب تحميلها نسبةً إلى جذر Plugin. |
| `name` | لا | `string` | اسم Plugin قابل للقراءة البشرية. |
| `description` | لا | `string` | ملخص قصير يُعرض في واجهات Plugin. |
| `version` | لا | `string` | إصدار Plugin لأغراض معلوماتية. |
| `uiHints` | لا | `Record<string, object>` | تسميات واجهة المستخدم، وplaceholder، وتلميحات الحساسية لحقول التكوين. |
## مرجع `providerAuthChoices`
يصف كل إدخال في `providerAuthChoices` خيار إعداد أولي أو مصادقة واحدًا.
يقرأ OpenClaw هذا قبل تحميل وقت تشغيل provider.
يصف كل إدخال في `providerAuthChoices` اختيار إعداد أولي أو مصادقة واحدًا.
يقرأ OpenClaw هذا قبل تحميل وقت تشغيل Provider.
| الحقل | مطلوب | النوع | المعنى |
| --------------------- | -------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `provider` | نعم | `string` | معرّف provider الذي ينتمي إليه هذا الخيار. |
| `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 <key>`. |
| `cliDescription` | لا | `string` | الوصف المستخدم في مساعدة CLI. |
| `onboardingScopes` | لا | `Array<"text-inference" \| "image-generation">` | أسطح الإعداد الأولي التي يجب أن يظهر فيها هذا الخيار. وإذا حُذفت، فالقيمة الافتراضية هي `["text-inference"]`. |
| الحقل | مطلوب | النوع | المعنى |
| --------------------- | ------ | ------------------------------------------------ | --------------------------------------------------------------------------------------------------- |
| `provider` | نعم | `string` | معرّف Provider الذي ينتمي إليه هذا الاختيار. |
| `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 <key>`. |
| `cliDescription` | لا | `string` | الوصف المستخدم في مساعدة CLI. |
| `onboardingScopes` | لا | `Array<"text-inference" \| "image-generation">` | أسطح الإعداد الأولي التي يجب أن يظهر فيها هذا الاختيار. إذا حُذفت، فالقيمة الافتراضية هي `["text-inference"]`. |
## مرجع `commandAliases`
استخدم `commandAliases` عندما يملك Plugin اسم أمر وقت تشغيل قد
يضعه المستخدمون خطأً في `plugins.allow` أو يحاولون تشغيله كأمر CLI جذري. يستخدم OpenClaw
هذه البيانات الوصفية للتشخيصات من دون استيراد كود وقت تشغيل Plugin.
استخدم `commandAliases` عندما يملك Plugin اسم أمر وقت تشغيل قد يقوم المستخدمون
عن طريق الخطأ بوضعه في `plugins.allow` أو محاولة تشغيله كأمر CLI جذري. يستخدم OpenClaw
هذه البيانات التعريفية للتشخيصات من دون استيراد كود وقت تشغيل Plugin.
```json
{
@ -227,44 +224,45 @@ x-i18n:
}
```
| الحقل | مطلوب | النوع | المعنى |
| ------------ | -------- | ----------------- | ----------------------------------------------------------------------- |
| `name` | نعم | `string` | اسم الأمر الذي ينتمي إلى هذا الـ Plugin. |
| `kind` | لا | `"runtime-slash"` | يضع علامة على الاسم المستعار باعتباره أمر slash في الدردشة وليس أمر CLI جذريًا. |
| `cliCommand` | لا | `string` | أمر CLI جذري ذو صلة يُقترح لعمليات CLI، إن وُجد. |
| الحقل | مطلوب | النوع | المعنى |
| ------------ | ------ | ----------------- | ----------------------------------------------------------------------- |
| `name` | نعم | `string` | اسم الأمر الذي ينتمي إلى هذا Plugin. |
| `kind` | لا | `"runtime-slash"` | يحدد أن الاسم المستعار هو أمر slash للدردشة وليس أمر CLI جذريًا. |
| `cliCommand` | لا | `string` | أمر CLI جذري ذو صلة لاقتراحه في عمليات CLI، إذا كان موجودًا. |
## مرجع `activation`
استخدم `activation` عندما يستطيع Plugin أن يعلن بشكل رخيص عن أحداث طبقة التحكم
التي ينبغي أن تفعّله لاحقًا.
استخدم `activation` عندما يستطيع Plugin التصريح بكلفة منخفضة عن أحداث طبقة التحكم
التي يجب أن تفعّله لاحقًا.
## مرجع `qaRunners`
استخدم `qaRunners` عندما يساهم Plugin بواحد أو أكثر من مشغلات النقل تحت
الجذر المشترك `openclaw qa`. حافظ على هذه البيانات الوصفية رخيصة وثابتة؛ فما يزال وقت تشغيل Plugin يملك تسجيل CLI الفعلي من خلال سطح
خفيف `runtime-api.ts` يصدّر `qaRunnerCliRegistrations`.
استخدم `qaRunners` عندما يساهم Plugin بمشغّل نقل واحد أو أكثر تحت الجذر
المشترك `openclaw qa`. حافظ على هذه البيانات التعريفية منخفضة الكلفة وثابتة؛ إذ إن وقت تشغيل Plugin
لا يزال يملك تسجيل CLI الفعلي عبر سطح
`runtime-api.ts` خفيف الوزن الذي يصدّر `qaRunnerCliRegistrations`.
```json
{
"qaRunners": [
{
"commandName": "matrix",
"description": "تشغيل مسار QA الحي المدعوم بـ Docker لـ Matrix مقابل homeserver مؤقت"
"description": "Run the Docker-backed Matrix live QA lane against a disposable homeserver"
}
]
}
```
| الحقل | مطلوب | النوع | المعنى |
| ------------- | -------- | -------- | ------------------------------------------------------------------ |
| `commandName` | نعم | `string` | الأمر الفرعي المركّب تحت `openclaw qa`، مثل `matrix`. |
| `description` | لا | `string` | نص مساعدة احتياطي يُستخدم عندما يحتاج المضيف المشترك إلى أمر stub. |
| الحقل | مطلوب | النوع | المعنى |
| ------------- | ------ | --------- | ----------------------------------------------------------------- |
| `commandName` | نعم | `string` | الأمر الفرعي المركّب تحت `openclaw qa`، مثل `matrix`. |
| `description` | لا | `string` | نص مساعدة بديل يُستخدم عندما يحتاج المضيف المشترك إلى أمر وهمي. |
هذه الكتلة بيانات وصفية فقط. فهي لا تسجل سلوك وقت التشغيل، كما أنها لا
هذه الكتلة مخصصة للبيانات التعريفية فقط. فهي لا تسجل سلوك وقت التشغيل، ولا
تحل محل `register(...)` أو `setupEntry` أو نقاط دخول وقت التشغيل/Plugin الأخرى.
يستخدمها المستهلكون الحاليون كتلميح تضييق قبل تحميل Plugin الأوسع، لذلك فإن
غياب بيانات التفعيل الوصفية يكلف عادةً الأداء فقط؛ ولا ينبغي أن
يغيّر الصحة ما دامت بدائل ملكية الـ Manifest القديمة ما تزال موجودة.
ويستخدمها المستهلكون الحاليون كتلميح تضييق قبل تحميل أوسع للـ Plugin، لذلك فإن
غياب بيانات تعريف `activation` يكلّف عادةً الأداء فقط؛ ولا ينبغي أن
يغيّر الصحة ما دامت آليات الرجوع القديمة لملكية البيان لا تزال موجودة.
```json
{
@ -278,28 +276,29 @@ x-i18n:
}
```
| الحقل | مطلوب | النوع | المعنى |
| ---------------- | -------- | ---------------------------------------------------- | ----------------------------------------------------------------- |
| `onProviders` | لا | `string[]` | معرّفات provider التي ينبغي أن تفعّل هذا الـ Plugin عند طلبها. |
| `onCommands` | لا | `string[]` | معرّفات الأوامر التي ينبغي أن تفعّل هذا الـ Plugin. |
| `onChannels` | لا | `string[]` | معرّفات القنوات التي ينبغي أن تفعّل هذا الـ Plugin. |
| `onRoutes` | لا | `string[]` | أنواع routes التي ينبغي أن تفعّل هذا الـ Plugin. |
| `onCapabilities` | لا | `Array<"provider" \| "channel" \| "tool" \| "hook">` | تلميحات قدرات عامة تُستخدم بواسطة تخطيط التفعيل في طبقة التحكم. |
| الحقل | مطلوب | النوع | المعنى |
| ---------------- | ------ | ---------------------------------------------------- | ------------------------------------------------------------- |
| `onProviders` | لا | `string[]` | معرّفات Providers التي يجب أن تفعّل هذا Plugin عند طلبها. |
| `onCommands` | لا | `string[]` | معرّفات الأوامر التي يجب أن تفعّل هذا Plugin. |
| `onChannels` | لا | `string[]` | معرّفات القنوات التي يجب أن تفعّل هذا Plugin. |
| `onRoutes` | لا | `string[]` | أنواع المسارات التي يجب أن تفعّل هذا Plugin. |
| `onCapabilities` | لا | `Array<"provider" \| "channel" \| "tool" \| "hook">` | تلميحات قدرات عامة تُستخدم في تخطيط التنشيط في طبقة التحكم. |
المستهلكون الفعليون الحاليون:
- يعود تخطيط CLI المحفَّز بالأوامر إلى الصيغة القديمة
- يعود تخطيط CLI المحفَّز بالأوامر إلى
`commandAliases[].cliCommand` أو `commandAliases[].name`
- يعود تخطيط الإعداد/القنوات المحفَّز بالقنوات إلى الملكية القديمة `channels[]`
عندما تكون بيانات تفعيل القناة الصريحة مفقودة
- يعود تخطيط الإعداد/وقت التشغيل المحفَّز بالـ provider إلى الملكية القديمة
`providers[]` وملكية `cliBackends[]` ذات المستوى الأعلى عندما تكون
بيانات تفعيل provider الصريحة مفقودة
القديمين
- يعود تخطيط الإعداد/القنوات المحفَّز بالقنوات إلى ملكية
`channels[]` القديمة عندما تغيب بيانات تعريف تنشيط القناة الصريحة
- يعود تخطيط الإعداد/وقت التشغيل المحفَّز بالـ Provider إلى
ملكية `providers[]` القديمة وملكية `cliBackends[]` ذات المستوى الأعلى
عندما تغيب بيانات تعريف تنشيط Provider الصريحة
## مرجع `setup`
استخدم `setup` عندما تحتاج أسطح الإعداد والإعداد الأولي إلى بيانات وصفية رخيصة يملكها Plugin
قبل تحميل وقت التشغيل.
استخدم `setup` عندما تحتاج أسطح الإعداد والتهيئة الأولية إلى بيانات تعريف منخفضة الكلفة
مملوكة للـ Plugin قبل تحميل وقت التشغيل.
```json
{
@ -318,48 +317,48 @@ x-i18n:
}
```
يظل `cliBackends` ذو المستوى الأعلى صالحًا ويستمر في وصف
backends الاستدلال عبر CLI. أما `setup.cliBackends` فهو سطح الوصف الخاص بالإعداد
لتدفقات طبقة التحكم/الإعداد التي ينبغي أن تبقى بيانات وصفية فقط.
يبقى `cliBackends` في المستوى الأعلى صالحًا ويستمر في وصف
واجهات CLI الخلفية للاستدلال. أما `setup.cliBackends` فهو سطح الواصفات الخاص بالإعداد
لتدفقات طبقة التحكم/الإعداد التي يجب أن تبقى بيانات تعريف فقط.
عند وجوده، يكون `setup.providers` و`setup.cliBackends` هما السطح المفضل
للبحث القائم على الوصف أولًا في اكتشاف الإعداد. وإذا كان الوصف يضيّق فقط نطاق Plugin المرشح
ولا يزال الإعداد يحتاج إلى hooks أغنى لوقت الإعداد،
فاضبط `requiresRuntime: true` وأبقِ `setup-api` في مكانه بوصفه
مسار التنفيذ الاحتياطي.
عند وجودهما، يكون `setup.providers` و`setup.cliBackends` هما
سطح البحث المفضل أولًا بالواصفات لاكتشاف الإعداد. وإذا كان الواصف يضيّق فقط
Plugin المرشح وكان الإعداد لا يزال يحتاج إلى hooks أغنى لوقت الإعداد،
فعَيّن `requiresRuntime: true` وأبقِ `setup-api` في مكانه كمسار تنفيذ
بديل.
ولأن البحث في الإعداد يمكن أن ينفذ كود `setup-api` المملوك للـ Plugin، فيجب أن تبقى
القيم المطبعّة `setup.providers[].id` و`setup.cliBackends[]` فريدة عبر
Plugins المكتشفة. وتفشل الملكية الملتبسة فشلًا مغلقًا بدلًا من اختيار
ولأن بحث الإعداد قد ينفذ كود `setup-api` مملوكًا للـ Plugin، يجب أن
تبقى القيم المطبعّة في `setup.providers[].id` و`setup.cliBackends[]` فريدة عبر
Plugins المكتشفة. وتفشل الملكية الملتبسة بإغلاق صارم بدلًا من اختيار
فائز حسب ترتيب الاكتشاف.
### مرجع `setup.providers`
| الحقل | مطلوب | النوع | المعنى |
| ------------- | -------- | ---------- | ------------------------------------------------------------------------------------ |
| `id` | نعم | `string` | معرّف provider المعروض أثناء الإعداد أو الإعداد الأولي. حافظ على فرادة المعرفات المطبعّة عالميًا. |
| `authMethods` | لا | `string[]` | معرّفات أساليب الإعداد/المصادقة التي يدعمها هذا الـ provider من دون تحميل وقت التشغيل الكامل. |
| `envVars` | لا | `string[]` | متغيرات env التي يمكن لأسطح الإعداد/الحالة العامة فحصها قبل تحميل وقت تشغيل Plugin. |
| الحقل | مطلوب | النوع | المعنى |
| ------------- | ------ | ---------- | -------------------------------------------------------------------------------- |
| `id` | نعم | `string` | معرّف Provider المعروض أثناء الإعداد أو التهيئة الأولية. حافظ على فرادة المعرّفات المطبعّة عالميًا. |
| `authMethods` | لا | `string[]` | معرّفات طرق الإعداد/المصادقة التي يدعمها هذا Provider من دون تحميل وقت التشغيل الكامل. |
| `envVars` | لا | `string[]` | متغيرات البيئة التي يمكن لأسطح الإعداد/الحالة العامة التحقق منها قبل تحميل وقت تشغيل Plugin. |
### حقول `setup`
| الحقل | مطلوب | النوع | المعنى |
| ------------------ | -------- | ---------- | --------------------------------------------------------------------------------------------------- |
| `providers` | لا | `object[]` | واصفات إعداد provider المعروضة أثناء الإعداد والإعداد الأولي. |
| `cliBackends` | لا | `string[]` | معرّفات backend وقت الإعداد المستخدمة في البحث القائم على الوصف أولًا. حافظ على فرادة المعرفات المطبعّة عالميًا. |
| `configMigrations` | لا | `string[]` | معرّفات ترحيل التكوين التي يملكها سطح الإعداد الخاص بهذا الـ Plugin. |
| `requiresRuntime` | لا | `boolean` | ما إذا كان الإعداد لا يزال يحتاج إلى تنفيذ `setup-api` بعد البحث الوصفي. |
| الحقل | مطلوب | النوع | المعنى |
| ------------------ | ------ | ---------- | ------------------------------------------------------------------------------------------------ |
| `providers` | لا | `object[]` | واصفات إعداد Provider المعروضة أثناء الإعداد والتهيئة الأولية. |
| `cliBackends` | لا | `string[]` | معرّفات الواجهات الخلفية وقت الإعداد المستخدمة للبحث أولًا بالواصفات. حافظ على فرادة المعرّفات المطبعّة عالميًا. |
| `configMigrations` | لا | `string[]` | معرّفات ترحيل التكوين التي يملكها سطح الإعداد الخاص بهذا Plugin. |
| `requiresRuntime` | لا | `boolean` | ما إذا كان الإعداد لا يزال يحتاج إلى تنفيذ `setup-api` بعد البحث بالواصفات. |
## مرجع `uiHints`
`uiHints` هي خريطة من أسماء حقول التكوين إلى تلميحات عرض صغيرة.
يمثل `uiHints` خريطة من أسماء حقول التكوين إلى تلميحات عرض صغيرة.
```json
{
"uiHints": {
"apiKey": {
"label": "API key",
"help": "تُستخدم لطلبات OpenRouter",
"help": "Used for OpenRouter requests",
"placeholder": "sk-or-v1-...",
"sensitive": true
}
@ -369,18 +368,18 @@ Plugins المكتشفة. وتفشل الملكية الملتبسة فشلًا
يمكن أن يتضمن كل تلميح حقل:
| الحقل | النوع | المعنى |
| الحقل | النوع | المعنى |
| ------------- | ---------- | --------------------------------------- |
| `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` | نص placeholder لمدخلات النماذج. |
## مرجع `contracts`
استخدم `contracts` فقط لبيانات ملكية القدرات الثابتة التي يستطيع OpenClaw
استخدم `contracts` فقط لبيانات تعريف ملكية القدرات الثابتة التي يمكن لـ OpenClaw
قراءتها من دون استيراد وقت تشغيل Plugin.
```json
@ -403,30 +402,30 @@ Plugins المكتشفة. وتفشل الملكية الملتبسة فشلًا
كل قائمة اختيارية:
| الحقل | النوع | المعنى |
| -------------------------------- | ---------- | ----------------------------------------------------------------- |
| `embeddedExtensionFactories` | `string[]` | معرّفات وقت التشغيل المضمّنة التي قد يسجّل Plugin مضمّن factories لها. |
| `externalAuthProviders` | `string[]` | معرّفات provider التي يملك هذا الـ Plugin hook ملف تعريف المصادقة الخارجية الخاص بها. |
| `speechProviders` | `string[]` | معرّفات مزودي الكلام التي يملكها هذا الـ Plugin. |
| `realtimeTranscriptionProviders` | `string[]` | معرّفات مزودي النسخ الفوري التي يملكها هذا الـ Plugin. |
| `realtimeVoiceProviders` | `string[]` | معرّفات مزودي الصوت الفوري التي يملكها هذا الـ Plugin. |
| `mediaUnderstandingProviders` | `string[]` | معرّفات مزودي فهم الوسائط التي يملكها هذا الـ Plugin. |
| `imageGenerationProviders` | `string[]` | معرّفات مزودي توليد الصور التي يملكها هذا الـ Plugin. |
| `videoGenerationProviders` | `string[]` | معرّفات مزودي توليد الفيديو التي يملكها هذا الـ Plugin. |
| `webFetchProviders` | `string[]` | معرّفات مزودي جلب الويب التي يملكها هذا الـ Plugin. |
| `webSearchProviders` | `string[]` | معرّفات مزودي البحث في الويب التي يملكها هذا الـ Plugin. |
| `tools` | `string[]` | أسماء أدوات الوكيل التي يملكها هذا الـ Plugin لفحوصات العقود المضمّنة. |
| الحقل | النوع | المعنى |
| -------------------------------- | ---------- | ------------------------------------------------------------------ |
| `embeddedExtensionFactories` | `string[]` | معرّفات وقت التشغيل المضمّنة التي يمكن لـ Plugin مضمّن تسجيل factories لها. |
| `externalAuthProviders` | `string[]` | معرّفات Providers التي يملك هذا Plugin hook ملف تعريف المصادقة الخارجية الخاص بها. |
| `speechProviders` | `string[]` | معرّفات Providers للكلام التي يملكها هذا Plugin. |
| `realtimeTranscriptionProviders` | `string[]` | معرّفات Providers للنسخ الفوري التي يملكها هذا Plugin. |
| `realtimeVoiceProviders` | `string[]` | معرّفات Providers للصوت الفوري التي يملكها هذا Plugin. |
| `mediaUnderstandingProviders` | `string[]` | معرّفات Providers لفهم الوسائط التي يملكها هذا Plugin. |
| `imageGenerationProviders` | `string[]` | معرّفات Providers لتوليد الصور التي يملكها هذا Plugin. |
| `videoGenerationProviders` | `string[]` | معرّفات Providers لتوليد الفيديو التي يملكها هذا Plugin. |
| `webFetchProviders` | `string[]` | معرّفات Providers لجلب الويب التي يملكها هذا Plugin. |
| `webSearchProviders` | `string[]` | معرّفات Providers للبحث في الويب التي يملكها هذا Plugin. |
| `tools` | `string[]` | أسماء أدوات الوكيل التي يملكها هذا Plugin لفحوصات العقود المجمعة. |
ينبغي لموفري الخدمة الذين ينفذون `resolveExternalAuthProfiles` أن يعلنوا
`contracts.externalAuthProviders`. أما Plugins التي لا تتضمن هذا الإعلان فما تزال تعمل
عبر fallback توافق قديم، لكن هذا fallback أبطأ
وسيُزال بعد نافذة الترحيل.
يجب على Plugins الخاصة بالـ Providers التي تنفذ `resolveExternalAuthProfiles` التصريح بـ
`contracts.externalAuthProviders`. أما Plugins التي لا تتضمن هذا التصريح فما تزال تعمل
عبر آلية توافق قديمة متراجعة، لكن هذه الآلية أبطأ
وسيتم إزالتها بعد انتهاء نافذة الترحيل.
## مرجع `mediaUnderstandingProviderMetadata`
استخدم `mediaUnderstandingProviderMetadata` عندما يكون لدى مزود فهم الوسائط
نماذج افتراضية، أو أولوية fallback تلقائي للمصادقة، أو دعم أصلي للمستندات
تحتاجه مساعدات core العامة قبل تحميل وقت التشغيل. كما يجب التصريح عن المفاتيح في
استخدم `mediaUnderstandingProviderMetadata` عندما يكون لدى Provider لفهم الوسائط
نماذج افتراضية، أو أولوية رجوع تلقائي للمصادقة، أو دعم أصلي للمستندات
تحتاج إليه مساعدات النواة العامة قبل تحميل وقت التشغيل. ويجب أيضًا التصريح عن المفاتيح في
`contracts.mediaUnderstandingProviders`.
```json
@ -450,18 +449,18 @@ Plugins المكتشفة. وتفشل الملكية الملتبسة فشلًا
}
```
يمكن أن يتضمن كل إدخال provider:
يمكن أن يتضمن كل إدخال Provider:
| الحقل | النوع | المعنى |
| ---------------------- | ----------------------------------- | ---------------------------------------------------------------------------- |
| `capabilities` | `("image" \| "audio" \| "video")[]` | قدرات الوسائط التي يكشفها هذا الـ provider. |
| `defaultModels` | `Record<string, string>` | القيم الافتراضية من القدرة إلى النموذج المستخدمة عندما لا يحدد التكوين نموذجًا. |
| `autoPriority` | `Record<string, number>` | تُرتّب الأرقام الأقل أولًا من أجل fallback التلقائي للـ provider المعتمد على بيانات الاعتماد. |
| `nativeDocumentInputs` | `"pdf"[]` | المدخلات الأصلية للمستندات التي يدعمها الـ provider. |
| ---------------------- | ----------------------------------- | --------------------------------------------------------------------- |
| `capabilities` | `("image" \| "audio" \| "video")[]` | قدرات الوسائط التي يوفّرها هذا Provider. |
| `defaultModels` | `Record<string, string>` | القيم الافتراضية من القدرة إلى النموذج المستخدمة عندما لا يحدد التكوين نموذجًا. |
| `autoPriority` | `Record<string, number>` | تُرتَّب الأرقام الأقل أولًا في الرجوع التلقائي إلى Provider المستند إلى بيانات الاعتماد. |
| `nativeDocumentInputs` | `"pdf"[]` | مدخلات المستندات الأصلية التي يدعمها Provider. |
## مرجع `channelConfigs`
استخدم `channelConfigs` عندما يحتاج Plugin قناة إلى بيانات وصفية رخيصة للتكوين قبل
استخدم `channelConfigs` عندما يحتاج Plugin قناة إلى بيانات تعريف تكوين منخفضة الكلفة قبل
تحميل وقت التشغيل.
```json
@ -477,12 +476,12 @@ Plugins المكتشفة. وتفشل الملكية الملتبسة فشلًا
},
"uiHints": {
"homeserverUrl": {
"label": "URL الخاص بـ Homeserver",
"label": "Homeserver URL",
"placeholder": "https://matrix.example.com"
}
},
"label": "Matrix",
"description": "اتصال Matrix homeserver",
"description": "Matrix homeserver connection",
"preferOver": ["matrix-legacy"]
}
}
@ -491,19 +490,19 @@ Plugins المكتشفة. وتفشل الملكية الملتبسة فشلًا
يمكن أن يتضمن كل إدخال قناة:
| الحقل | النوع | المعنى |
| ------------- | ------------------------ | ----------------------------------------------------------------------------------------- |
| `schema` | `object` | مخطط JSON لـ `channels.<id>`. وهو مطلوب لكل إدخال مُعلن لتكوين القناة. |
| `uiHints` | `Record<string, object>` | تسميات/عناصر نائبة/تلميحات حساسة اختيارية لـ UI لقسم تكوين تلك القناة. |
| `label` | `string` | تسمية القناة المدمجة في أسطح المنتقي والفحص عندما لا تكون بيانات وقت التشغيل الوصفية جاهزة. |
| `description` | `string` | وصف قصير للقناة لأسطح الفحص والكتالوج. |
| `preferOver` | `string[]` | معرّفات Plugins قديمة أو أقل أولوية يجب أن تتفوق عليها هذه القناة في أسطح الاختيار. |
| الحقل | النوع | المعنى |
| ------------- | ------------------------ | ---------------------------------------------------------------------------------- |
| `schema` | `object` | مخطط JSON لـ `channels.<id>`. وهو مطلوب لكل إدخال تكوين قناة مُصرّح به. |
| `uiHints` | `Record<string, object>` | تسميات/placeholder/تلميحات حساسية اختيارية لواجهة المستخدم لهذا القسم من تكوين القناة. |
| `label` | `string` | تسمية القناة المدمجة في واجهات المنتقي والفحص عندما لا تكون بيانات تعريف وقت التشغيل جاهزة. |
| `description` | `string` | وصف قصير للقناة لواجهات الفحص والكتالوج. |
| `preferOver` | `string[]` | معرّفات Plugins قديمة أو أقل أولوية يجب أن تتقدم عليها هذه القناة في واجهات الاختيار. |
## مرجع `modelSupport`
استخدم `modelSupport` عندما ينبغي لـ OpenClaw أن يستنتج Plugin provider الخاص بك من
معرّفات نماذج مختصرة مثل `gpt-5.4` أو `claude-sonnet-4.6` قبل تحميل
وقت تشغيل Plugin.
استخدم `modelSupport` عندما يجب على OpenClaw استنتاج Plugin الـ Provider الخاص بك من
معرّفات نماذج مختصرة مثل `gpt-5.4` أو `claude-sonnet-4.6` قبل وقت تشغيل Plugin
التحميل.
```json
{
@ -514,100 +513,102 @@ Plugins المكتشفة. وتفشل الملكية الملتبسة فشلًا
}
```
يطبق OpenClaw ترتيب الأولوية هذا:
يطبّق OpenClaw أولوية الترتيب التالية:
- تستخدم مراجع `provider/model` الصريحة بيانات Manifest الوصفية المملوكة لـ `providers`
- تستخدم مراجع `provider/model` الصريحة بيانات تعريف البيان `providers` المالكة
- تتغلب `modelPatterns` على `modelPrefixes`
- إذا طابق كل من Plugin غير مضمّن وPlugin مضمّن، فإن Plugin
غير المضمّن يفوز
- يُتجاهل الغموض المتبقي إلى أن يحدد المستخدم أو التكوين provider
- إذا طابق كل من Plugin غير مضمّن وPlugin مضمّن، يفوز Plugin
غير المضمّن
- يتم تجاهل أي غموض متبقٍ حتى يحدد المستخدم أو التكوين Provider
الحقول:
| الحقل | النوع | المعنى |
| --------------- | ---------- | ------------------------------------------------------------------------------- |
| `modelPrefixes` | `string[]` | بادئات تُطابق باستخدام `startsWith` مع معرّفات النماذج المختصرة. |
| `modelPatterns` | `string[]` | مصادر Regex تُطابق مع معرّفات النماذج المختصرة بعد إزالة لاحقة profile. |
| الحقل | النوع | المعنى |
| --------------- | ---------- | ------------------------------------------------------------------------ |
| `modelPrefixes` | `string[]` | بادئات تتم مطابقتها باستخدام `startsWith` مع معرّفات النماذج المختصرة. |
| `modelPatterns` | `string[]` | مصادر Regex تتم مطابقتها مع معرّفات النماذج المختصرة بعد إزالة لاحقة الملف التعريفي. |
إن مفاتيح القدرات القديمة ذات المستوى الأعلى مهجورة. استخدم `openclaw doctor --fix` من أجل
نقل `speechProviders` و`realtimeTranscriptionProviders` و
`realtimeVoiceProviders` و`mediaUnderstandingProviders` و
`imageGenerationProviders` و`videoGenerationProviders` و
`webFetchProviders` و`webSearchProviders` تحت `contracts`؛ فلم يعد
تحميل الـ Manifest العادي يتعامل مع تلك الحقول ذات المستوى الأعلى باعتبارها
مفاتيح القدرات القديمة في المستوى الأعلى متقادمة. استخدم `openclaw doctor --fix` من أجل
نقل `speechProviders` و`realtimeTranscriptionProviders`،
و`realtimeVoiceProviders` و`mediaUnderstandingProviders`،
و`imageGenerationProviders` و`videoGenerationProviders`،
و`webFetchProviders` و`webSearchProviders` إلى `contracts`؛ إذ إن
تحميل البيان العادي لم يعد يعامل تلك الحقول ذات المستوى الأعلى على أنها
ملكية للقدرات.
## Manifest مقابل package.json
## البيان مقابل package.json
يؤدي الملفان وظيفتين مختلفتين:
يخدم الملفان أغراضًا مختلفة:
| الملف | استخدمه من أجل |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `openclaw.plugin.json` | الاكتشاف، والتحقق من التكوين، وبيانات خيارات المصادقة الوصفية، وhints الخاصة بـ UI التي يجب أن توجد قبل تشغيل كود Plugin |
| `package.json` | بيانات npm الوصفية، وتثبيت التبعيات، وكتلة `openclaw` المستخدمة لنقاط الدخول، وتقييد التثبيت، والإعداد، أو بيانات الكتالوج الوصفية |
| الملف | استخدمه من أجل |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `openclaw.plugin.json` | الاكتشاف، والتحقق من التكوين، وبيانات تعريف اختيارات المصادقة، وتلميحات واجهة المستخدم التي يجب أن تكون موجودة قبل تشغيل كود Plugin |
| `package.json` | بيانات تعريف npm، وتثبيت التبعيات، وكتلة `openclaw` المستخدمة لنقاط الدخول، أو تقييد التثبيت، أو الإعداد، أو بيانات تعريف الكتالوج |
إذا لم تكن متأكدًا من موضع جزء من البيانات الوصفية، فاستخدم هذه القاعدة:
إذا لم تكن متأكدًا من موضع قطعة من البيانات التعريفية، فاستخدم هذه القاعدة:
- إذا كان يجب على OpenClaw معرفته قبل تحميل كود Plugin، فضعه في `openclaw.plugin.json`
- وإذا كان متعلقًا بالتغليف أو ملفات الدخول أو سلوك تثبيت npm، فضعه في `package.json`
- إذا كان يجب على OpenClaw معرفتها قبل تحميل كود Plugin، فضعها في `openclaw.plugin.json`
- إذا كانت تتعلق بالتغليف، أو ملفات الدخول، أو سلوك تثبيت npm، فضعها في `package.json`
### حقول `package.json` التي تؤثر في الاكتشاف
توجد بعض بيانات Plugin الوصفية ما قبل وقت التشغيل عمدًا في `package.json` تحت
بعض بيانات تعريف Plugin قبل وقت التشغيل تعيش عمدًا في `package.json` ضمن
كتلة `openclaw` بدلًا من `openclaw.plugin.json`.
أمثلة مهمة:
| الحقل | المعنى |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `openclaw.extensions` | يعلن نقاط دخول Plugin الأصلية. ويجب أن تبقى داخل دليل حزمة Plugin. |
| `openclaw.runtimeExtensions` | يعلن نقاط دخول وقت التشغيل المبنية بـ JavaScript للحزم المثبتة. ويجب أن تبقى داخل دليل حزمة Plugin. |
| `openclaw.setupEntry` | نقطة دخول خفيفة خاصة بالإعداد فقط تُستخدم أثناء الإعداد الأولي، وبدء تشغيل القناة المؤجل، واكتشاف حالة القناة/SecretRef للقراءة فقط. ويجب أن تبقى داخل دليل حزمة Plugin. |
| `openclaw.runtimeSetupEntry` | يعلن نقطة دخول الإعداد المبنية بـ JavaScript للحزم المثبتة. ويجب أن تبقى داخل دليل حزمة Plugin. |
| `openclaw.channel` | بيانات وصفية رخيصة لكتالوج القنوات مثل التسميات، ومسارات الوثائق، والأسماء المستعارة، ونصوص الاختيار. |
| `openclaw.channel.configuredState` | بيانات وصفية خفيفة لمدقق حالة التكوين تستطيع الإجابة عن سؤال "هل يوجد إعداد قائم يعتمد على env فقط بالفعل؟" من دون تحميل وقت تشغيل القناة الكامل. |
| `openclaw.channel.persistedAuthState` | بيانات وصفية خفيفة لمدقق حالة المصادقة المحفوظة تستطيع الإجابة عن سؤال "هل تم تسجيل الدخول بالفعل إلى أي شيء؟" من دون تحميل وقت تشغيل القناة الكامل. |
| الحقل | المعنى |
| ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `openclaw.extensions` | يصرّح بنقاط دخول Plugin الأصلية. يجب أن تبقى داخل دليل حزمة Plugin. |
| `openclaw.runtimeExtensions` | يصرّح بنقاط دخول وقت التشغيل المبنية بـ JavaScript للحزم المثبتة. يجب أن تبقى داخل دليل حزمة Plugin. |
| `openclaw.setupEntry` | نقطة دخول خفيفة مخصصة للإعداد فقط تُستخدم أثناء التهيئة الأولية، وبدء تشغيل القنوات المؤجل، واكتشاف حالة القناة/SecretRef للقراءة فقط. يجب أن تبقى داخل دليل حزمة Plugin. |
| `openclaw.runtimeSetupEntry` | يصرّح بنقطة دخول إعداد JavaScript المبنية للحزم المثبتة. يجب أن تبقى داخل دليل حزمة Plugin. |
| `openclaw.channel` | بيانات تعريف منخفضة الكلفة لكتالوج القنوات مثل التسميات، ومسارات الوثائق، والأسماء المستعارة، ونصوص الاختيار. |
| `openclaw.channel.configuredState` | بيانات تعريف خفيفة لفاحص الحالة المكوَّنة يمكنها الإجابة عن سؤال "هل يوجد إعداد يعتمد على env فقط بالفعل؟" من دون تحميل وقت تشغيل القناة الكامل. |
| `openclaw.channel.persistedAuthState` | بيانات تعريف خفيفة لفاحص المصادقة المخزنة يمكنها الإجابة عن سؤال "هل تم تسجيل الدخول إلى أي شيء بالفعل؟" من دون تحميل وقت تشغيل القناة الكامل. |
| `openclaw.install.npmSpec` / `openclaw.install.localPath` | تلميحات التثبيت/التحديث للـ Plugins المضمّنة والمنشورة خارجيًا. |
| `openclaw.install.defaultChoice` | مسار التثبيت المفضل عند توفر مصادر تثبيت متعددة. |
| `openclaw.install.minHostVersion` | الحد الأدنى لإصدار مضيف OpenClaw المدعوم، باستخدام حد semver أدنى مثل `>=2026.3.22`. |
| `openclaw.install.expectedIntegrity` | سلسلة سلامة npm dist المتوقعة مثل `sha512-...`؛ وتتحقق تدفقات التثبيت والتحديث من العنصر الذي تم جلبه مقابلها. |
| `openclaw.install.allowInvalidConfigRecovery` | يسمح بمسار استرداد ضيق لإعادة تثبيت Plugin مضمّن عندما يكون التكوين غير صالح. |
| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | يسمح لأسطح القنوات الخاصة بالإعداد فقط أن تُحمّل قبل Plugin القناة الكامل أثناء بدء التشغيل. |
| `openclaw.install.defaultChoice` | مسار التثبيت المفضّل عندما تتوفر عدة مصادر للتثبيت. |
| `openclaw.install.minHostVersion` | الحد الأدنى لإصدار مضيف OpenClaw المدعوم، باستخدام حد semver أدنى مثل `>=2026.3.22`. |
| `openclaw.install.expectedIntegrity` | سلسلة integrity المتوقعة من npm dist مثل `sha512-...`؛ تتحقق تدفقات التثبيت والتحديث من الأثر الذي تم جلبه مقارنةً بها. |
| `openclaw.install.allowInvalidConfigRecovery` | يسمح بمسار استرداد ضيق لإعادة تثبيت Plugin مضمّن عندما يكون التكوين غير صالح. |
| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | يتيح لواجهات القنوات المخصصة للإعداد فقط أن تُحمَّل قبل Plugin القناة الكامل أثناء بدء التشغيل. |
تحدد بيانات الـ Manifest الوصفية أي خيارات provider/channel/setup تظهر في
الإعداد الأولي قبل تحميل وقت التشغيل. وتخبر `package.json#openclaw.install`
الإعداد الأولي بكيفية جلب ذلك الـ Plugin أو تفعيله عندما يختار المستخدم أحد تلك
تحدد بيانات تعريف البيان خيارات Provider/القناة/الإعداد التي تظهر في
التهيئة الأولية قبل تحميل وقت التشغيل. ويخبر `package.json#openclaw.install`
التهيئة الأولية بكيفية جلب ذلك Plugin أو تمكينه عندما يختار المستخدم أحد تلك
الخيارات. لا تنقل تلميحات التثبيت إلى `openclaw.plugin.json`.
يُفرض `openclaw.install.minHostVersion` أثناء التثبيت وتحميل سجل
Manifest. وتُرفض القيم غير الصالحة؛ أما القيم الأحدث لكن الصالحة فتتخطى
يُفرض `openclaw.install.minHostVersion` أثناء التثبيت وتحميل
سجل البيان. تُرفض القيم غير الصالحة؛ أما القيم الأحدث ولكن الصالحة فتتجاوز
Plugin على المضيفين الأقدم.
يوجد بالفعل تثبيت إصدار npm الدقيق في `npmSpec`، على سبيل المثال
توجد آلية التثبيت الدقيق لإصدار npm بالفعل في `npmSpec`، مثل
`"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`. واقرن ذلك مع
`expectedIntegrity` عندما تريد أن تفشل تدفقات التحديث فشلًا مغلقًا إذا لم يعد
عنصر npm الذي جُلب يطابق الإصدار المثبّت. ولا يقدّم الإعداد الأولي التفاعلي إلا
خيارات تثبيت npm من بيانات كتالوج موثوقة عندما يكون `npmSpec` إصدارًا
دقيقًا وكانت `expectedIntegrity` موجودة؛ وإلا فإنه يعود إلى
مصدر محلي أو التخطي.
`expectedIntegrity` عندما تريد أن تفشل تدفقات التحديث بإغلاق صارم إذا لم يعد
أثر npm الذي تم جلبه يطابق الإصدار المثبّت. تعرض التهيئة الأولية التفاعلية
مواصفات npm الخاصة بالسجل الموثوق، بما في ذلك أسماء الحزم المجردة ووسوم dist-tags.
وعندما يكون `expectedIntegrity` موجودًا، تفرض تدفقات التثبيت/التحديث ذلك؛ وعندما
يُحذف، يُسجَّل حل السجل من دون تثبيت integrity.
ينبغي لـ Plugins القنوات أن توفر `openclaw.setupEntry` عندما تحتاج الحالة أو قائمة القنوات
أو فحوصات SecretRef إلى تحديد الحسابات المكوّنة من دون تحميل
وقت التشغيل الكامل. ويجب أن تكشف نقطة الإعداد بيانات القناة الوصفية بالإضافة إلى
مهايئات آمنة للإعداد تخص التكوين والحالة والأسرار؛ مع إبقاء عملاء الشبكة ومستمعي Gateway و
أوقات تشغيل النقل في نقطة دخول الامتداد الرئيسية.
يجب على Plugins القنوات توفير `openclaw.setupEntry` عندما تحتاج عمليات الحالة،
أو قائمة القنوات، أو فحص SecretRef إلى تحديد الحسابات المكوَّنة من دون تحميل وقت التشغيل
الكامل. ينبغي أن تكشف نقطة دخول الإعداد عن بيانات تعريف القناة، إضافةً إلى
مهايئات آمنة للإعداد خاصة بالتكوين والحالة والأسرار؛ وأبقِ عملاء الشبكة،
ومستمعي Gateway، وأوقات تشغيل النقل في نقطة دخول الامتداد الرئيسية.
لا تتجاوز حقول نقطة دخول وقت التشغيل فحوصات حدود الحزم لحقول
نقطة دخول المصدر. فعلى سبيل المثال، لا يمكن لـ `openclaw.runtimeExtensions`
أن تجعل مسار `openclaw.extensions` الهارب قابلاً للتحميل.
لا تتجاوز حقول نقاط دخول وقت التشغيل فحوصات حدود الحزمة الخاصة بحقوق
نقطة دخول المصدر. على سبيل المثال، لا يمكن لـ `openclaw.runtimeExtensions` أن تجعل
مسار `openclaw.extensions` الهارب قابلًا للتحميل.
إن `openclaw.install.allowInvalidConfigRecovery` ضيق عمدًا. فهو
لا يجعل التكوينات المعطوبة العشوائية قابلة للتثبيت. واليوم يسمح فقط لتدفقات التثبيت
بالتعافي من حالات فشل معينة قديمة أثناء ترقية Plugin مضمّن، مثل
غياب مسار Plugin المضمّن أو وجود إدخال `channels.<id>` قديم لذلك الـ Plugin المضمّن نفسه. وتظل أخطاء التكوين غير المرتبطة تمنع التثبيت وتوجّه المشغّلين
لا يجعل التكوينات المعطلة العشوائية قابلة للتثبيت. واليوم لا يسمح إلا
لتدفقات التثبيت بالاسترداد من حالات فشل ترقية محددة قديمة لPlugin مضمّن، مثل
مسار Plugin مضمّن مفقود أو إدخال `channels.<id>` قديم لPlugin المضمّن نفسه. أما
أخطاء التكوين غير المرتبطة فما تزال تمنع التثبيت وتوجه المشغلين
إلى `openclaw doctor --fix`.
إن `openclaw.channel.persistedAuthState` هو بيانات حزمة وصفية لوحدة فحص صغيرة:
يمثل `openclaw.channel.persistedAuthState` بيانات تعريف حزمة لوحدة فحص
صغيرة:
```json
{
@ -623,11 +624,13 @@ Plugin على المضيفين الأقدم.
}
```
استخدمه عندما تحتاج تدفقات setup أو doctor أو configured-state إلى probe
مصادقة بسيط بنعم/لا قبل تحميل Plugin القناة الكامل. ويجب أن يكون التصدير المستهدف دالة صغيرة تقرأ الحالة المحفوظة فقط؛ ولا تمررها عبر barrel
استخدمه عندما تحتاج تدفقات الإعداد، أو doctor، أو الحالة المكوَّنة إلى
فحص مصادقة منخفض الكلفة بنعم/لا قبل تحميل Plugin القناة الكامل. يجب أن يكون
التصدير الهدف دالة صغيرة تقرأ الحالة المخزنة فقط؛ ولا تمررها عبر barrel
وقت تشغيل القناة الكامل.
يتبع `openclaw.channel.configuredState` الشكل نفسه لفحوصات التكوين الرخيصة المعتمدة على env فقط:
ويتبع `openclaw.channel.configuredState` الشكل نفسه لفحوصات الحالة
المكوَّنة الرخيصة المعتمدة على env فقط:
```json
{
@ -643,95 +646,96 @@ Plugin على المضيفين الأقدم.
}
```
استخدمه عندما تستطيع القناة الإجابة عن حالة التكوين من env أو مدخلات صغيرة أخرى
غير وقت التشغيل. وإذا كان الفحص يحتاج إلى حل كامل للتكوين أو إلى
وقت تشغيل القناة الحقيقي، فأبقِ ذلك المنطق في hook
`config.hasConfiguredState` الخاص بالـ Plugin بدلًا من ذلك.
استخدمه عندما تستطيع قناة ما الإجابة عن الحالة المكوَّنة من env أو مدخلات صغيرة أخرى
غير وقت التشغيل. وإذا كان الفحص يحتاج إلى حل التكوين الكامل أو إلى وقت تشغيل
القناة الحقيقي، فأبقِ ذلك المنطق في hook ‏`config.hasConfiguredState`
الخاص بالـ Plugin بدلًا من ذلك.
## أسبقية الاكتشاف (معرّفات Plugin المكررة)
## أولوية الاكتشاف (معرّفات Plugin المكررة)
يكتشف OpenClaw Plugins من عدة جذور (مضمّنة، وتثبيت عام، ومساحة العمل، ومسارات محددة صراحة في التكوين). وإذا اشترك اكتشافان في `id` نفسه، فيُحتفظ فقط بالـ Manifest ذي **الأسبقية الأعلى**؛ بينما تُسقط النسخ المكررة ذات الأسبقية الأدنى بدلًا من تحميلها بجواره.
يكتشف OpenClaw Plugins من عدة جذور (مضمّنة، وتثبيت عام، ومساحة عمل، ومسارات صريحة محددة في التكوين). إذا اشتركت عمليتا اكتشاف في المعرّف `id` نفسه، فسيُحتفَظ فقط بالبيان ذي **الأولوية الأعلى**؛ أما النسخ المكررة ذات الأولوية الأدنى فسيتم إسقاطها بدلًا من تحميلها إلى جانبه.
ترتيب الأسبقية من الأعلى إلى الأدنى:
الأولوية، من الأعلى إلى الأدنى:
1. **المحدد في التكوين** — مسار مثبت صراحة في `plugins.entries.<id>`
2. **المضمّن** — Plugins المشحونة مع OpenClaw
3. **التثبيت العام** — Plugins المثبتة في جذر Plugins العام الخاص بـ OpenClaw
1. **محددة في التكوين** — مسار مثبت صراحة في `plugins.entries.<id>`
2. **مضمّنة** — Plugins المشحونة مع OpenClaw
3. **تثبيت عام** — Plugins المثبتة في جذر Plugins العام الخاص بـ OpenClaw
4. **مساحة العمل** — Plugins المكتشفة نسبةً إلى مساحة العمل الحالية
الآثار المترتبة:
- لن تحجب نسخة متشعبة أو قديمة من Plugin مضمّن موجودة في مساحة العمل البناء المضمّن.
- لتجاوز Plugin مضمّن محليًا فعليًا، ثبّته عبر `plugins.entries.<id>` حتى يفوز بالأسبقية بدلًا من الاعتماد على اكتشاف مساحة العمل.
- تُسجَّل حالات إسقاط النسخ المكررة حتى يتمكن Doctor وتشخيصات بدء التشغيل من الإشارة إلى النسخة المُسقطة.
- لن تطغى نسخة متفرعة أو قديمة من Plugin مضمّن موجودة في مساحة العمل على البنية المضمّنة.
- لكي تتجاوز فعلًا Plugin مضمّنًا بآخر محلي، ثبّته عبر `plugins.entries.<id>` حتى يفوز بالأولوية بدلًا من الاعتماد على اكتشاف مساحة العمل.
- يُسجل إسقاط النسخ المكررة حتى تتمكن تشخيصات Doctor وبدء التشغيل من الإشارة إلى النسخة التي تم تجاهلها.
## متطلبات مخطط JSON
- **يجب أن يرفق كل Plugin مخطط JSON**، حتى إن كان لا يقبل أي تكوين.
- يُقبل مخطط فارغ (مثل `{ "type": "object", "additionalProperties": false }`).
- تُتحقق المخططات عند قراءة/كتابة التكوين، لا أثناء وقت التشغيل.
- **يجب على كل Plugin أن يشحن مخطط JSON**، حتى إذا كان لا يقبل أي تكوين.
- يُقبل مخطط فارغ (مثلًا، `{ "type": "object", "additionalProperties": false }`).
- يتم التحقق من المخططات وقت قراءة/كتابة التكوين، وليس وقت التشغيل.
## سلوك التحقق
- تُعد مفاتيح `channels.*` غير المعروفة **أخطاء**، ما لم يكن معرّف القناة معلنًا بواسطة
Manifest Plugin.
- تُعد مفاتيح `channels.*` غير المعروفة **أخطاء**، ما لم يكن معرّف القناة مصرّحًا به
بواسطة بيان Plugin.
- يجب أن تشير `plugins.entries.<id>` و`plugins.allow` و`plugins.deny` و`plugins.slots.*`
إلى معرّفات Plugin **قابلة للاكتشاف**. وتُعد المعرفات غير المعروفة **أخطاء**.
- إذا كان Plugin مثبتًا لكن الـ Manifest أو المخطط الخاص به مكسورًا أو مفقودًا،
يفشل التحقق ويبلغ Doctor عن خطأ Plugin.
- إذا كان تكوين Plugin موجودًا لكن Plugin **معطّل**، فسيُحتفظ بالتكوين وتظهر
إلى معرّفات Plugin **قابلة للاكتشاف**. وتُعد المعرّفات غير المعروفة **أخطاء**.
- إذا كان Plugin مثبتًا لكن لديه بيان أو مخطط معطّل أو مفقود،
يفشل التحقق ويبلّغ Doctor عن خطأ Plugin.
- إذا كان تكوين Plugin موجودًا لكن Plugin **معطّل**، فسيُحتفَظ بالتكوين وتظهر
**تحذير** في Doctor + السجلات.
راجع [مرجع التكوين](/ar/gateway/configuration) للاطلاع على مخطط `plugins.*` الكامل.
راجع [مرجع التكوين](/ar/gateway/configuration) للحصول على مخطط `plugins.*` الكامل.
## ملاحظات
- الـ Manifest **مطلوب للـ Plugins الأصلية في OpenClaw**، بما في ذلك التحميل من نظام الملفات المحلي.
- ما يزال وقت التشغيل يحمّل وحدة Plugin بشكل منفصل؛ فالـ Manifest مخصص فقط
- البيان **مطلوب للـ Plugins الأصلية في OpenClaw**، بما في ذلك التحميلات من نظام الملفات المحلي.
- لا يزال وقت التشغيل يحمّل وحدة Plugin بشكل منفصل؛ والبيان مخصص فقط
للاكتشاف + التحقق.
- تُحلّل Manifestات Plugins الأصلية باستخدام JSON5، لذلك تُقبل التعليقات والفواصل اللاحقة
والمفاتيح غير المحاطة بعلامات اقتباس ما دامت القيمة النهائية كائنًا.
- لا يقرأ مُحمّل Manifest إلا حقول Manifest الموثقة. تجنب إضافة
- تُحلَّل البيانات الأصلية باستخدام JSON5، لذلك تُقبل التعليقات، والفواصل اللاحقة،
والمفاتيح غير المقتبسة ما دامت القيمة النهائية لا تزال كائنًا.
- لا يقرأ محمّل البيان إلا الحقول الموثقة في البيان. تجنب إضافة
مفاتيح مخصصة ذات مستوى أعلى هنا.
- إن `providerAuthEnvVars` هو مسار البيانات الوصفية الرخيص لفحوصات المصادقة،
والتحقق من env-marker، والأسطح المشابهة لمصادقة provider التي يجب ألا تشغّل
وقت تشغيل Plugin فقط لفحص أسماء env.
- يتيح `providerAuthAliases` لمتغيرات provider إعادة استخدام
متغيرات env الخاصة بالمصادقة، وملفات تعريف المصادقة، والمصادقة المدعومة بالتكوين، وخيار إعداد API-key الخاص بـ provider آخر
من دون ترميز هذه العلاقة بشكل صلب في core.
- يتيح `providerEndpoints` لموفري الخدمة امتلاك بيانات وصفية بسيطة لمطابقة مضيف endpoint/baseUrl.
استخدمه فقط لفئات endpoint التي يدعمها core بالفعل؛
فالـ Plugin ما يزال يملك سلوك وقت التشغيل.
- إن `syntheticAuthRefs` هو مسار البيانات الوصفية الرخيص للـ hooks الاصطناعية الخاصة بالمصادقة والمملوكة للـ provider
والتي يجب أن تكون مرئية لاكتشاف النماذج البارد قبل وجود
سجل وقت التشغيل. ولا تُدرج إلا المراجع التي ينفذ فيها provider أو backend CLI في وقت التشغيل
فعلًا `resolveSyntheticAuth`.
- إن `nonSecretAuthMarkers` هو مسار البيانات الوصفية الرخيص للعناصر النائبة
الخاصة بـ API key والمملوكة للـ Plugin المضمّن، مثل علامات الاعتماد المحلية أو OAuth أو الاعتماد البيئي.
ويتعامل core مع هذه القيم باعتبارها غير سرية لعرض المصادقة وتدقيق الأسرار من دون
ترميز صلب للـ provider المالك.
- إن `channelEnvVars` هو مسار البيانات الوصفية الرخيص من أجل shell-env fallback، وطلبات الإعداد،
والأسطح المماثلة للقنوات التي يجب ألا تشغّل وقت تشغيل Plugin
فقط لفحص أسماء env. وأسماء env هي بيانات وصفية، وليست تفعيلًا
بحد ذاتها: فما تزال الحالة، والتدقيق، والتحقق من تسليم Cron، وغيرها من الأسطح
المخصصة للقراءة فقط تطبق ثقة Plugin وسياسة التفعيل الفعلية قبل أن
تتعامل مع متغير env باعتباره قناة مكوّنة.
- إن `providerAuthChoices` هو مسار البيانات الوصفية الرخيص لمنتقيات خيارات المصادقة،
وحل `--auth-choice`، وربط provider المفضل، وتسجيل إشارات CLI البسيطة في الإعداد الأولي قبل تحميل وقت تشغيل provider. أما بالنسبة إلى
بيانات wizard الوصفية وقت التشغيل التي تتطلب كود provider، فراجع
[hooks وقت تشغيل provider](/ar/plugins/architecture#provider-runtime-hooks).
- تُختار أنواع Plugins الحصرية عبر `plugins.slots.*`.
- يُختار `kind: "memory"` بواسطة `plugins.slots.memory`.
- يُختار `kind: "context-engine"` بواسطة `plugins.slots.contextEngine`
- يمثل `providerAuthEnvVars` مسار البيانات التعريفية منخفضة الكلفة لفحوصات المصادقة، والتحقق من
علامات env، وواجهات مصادقة Provider المماثلة التي يجب ألا تشغّل وقت تشغيل Plugin
فقط لفحص أسماء env.
- يسمح `providerAuthAliases` لمتغيرات Provider بإعادة استخدام
متغيرات env الخاصة بمصادقة Provider آخر، وملفات تعريف المصادقة، والمصادقة المعتمدة على التكوين،
وخيار إعداد مفتاح API، من دون ترميز صارم لهذه العلاقة في النواة.
- يسمح `providerEndpoints` لـ Plugins الخاصة بالـ Provider بامتلاك بيانات تعريف بسيطة لمطابقة
`host`/`baseUrl` الخاصة بـ endpoint. استخدمه فقط لفئات endpoint التي تدعمها النواة بالفعل؛
إذ لا يزال Plugin يملك سلوك وقت التشغيل.
- يمثل `syntheticAuthRefs` مسار البيانات التعريفية منخفضة الكلفة لـ hooks المصادقة الاصطناعية
المملوكة للـ Provider والتي يجب أن تكون مرئية لاكتشاف النماذج البارد قبل وجود
سجل وقت التشغيل. لا تُدرج إلا المراجع التي ينفذ فيها Provider وقت التشغيل أو CLI backend
فعليًا `resolveSyntheticAuth`.
- يمثل `nonSecretAuthMarkers` مسار البيانات التعريفية منخفضة الكلفة لعلامات
مفاتيح API البديلة المملوكة لPlugin مضمّن، مثل العلامات المحلية أو OAuth أو بيانات الاعتماد المحيطية.
تتعامل النواة مع هذه القيم على أنها غير سرية لأغراض عرض المصادقة وتدقيق الأسرار من دون
ترميز Provider المالك ترميزًا صارمًا.
- يمثل `channelEnvVars` مسار البيانات التعريفية منخفضة الكلفة للرجوع إلى shell-env،
ومطالبات الإعداد، وواجهات القنوات المماثلة التي يجب ألا تشغّل وقت تشغيل Plugin
فقط لفحص أسماء env. أسماء env هي بيانات تعريف وليست تنشيطًا
بحد ذاتها: فما تزال الحالة، والتدقيق، والتحقق من تسليم Cron، والواجهات الأخرى للقراءة فقط
تطبق سياسة ثقة Plugin وسياسة التنشيط الفعلية قبل أن
تعتبر متغير env قناة مكوَّنة.
- يمثل `providerAuthChoices` مسار البيانات التعريفية منخفضة الكلفة لمنتقيات اختيار المصادقة،
وحل `--auth-choice`، وربط Provider المفضل، وتسجيل إشارات CLI البسيطة في
التهيئة الأولية قبل تحميل وقت تشغيل Provider. أما بيانات تعريف معالج وقت التشغيل
التي تتطلب كود Provider، فراجع
[hooks وقت تشغيل Provider](/ar/plugins/architecture#provider-runtime-hooks).
- يتم اختيار أنواع Plugins الحصرية عبر `plugins.slots.*`.
- يتم اختيار `kind: "memory"` بواسطة `plugins.slots.memory`.
- يتم اختيار `kind: "context-engine"` بواسطة `plugins.slots.contextEngine`
(الافتراضي: `legacy` المضمّن).
- يمكن حذف `channels` و`providers` و`cliBackends` و`skills` عندما لا
يحتاجها Plugin.
- إذا كان Plugin يعتمد على وحدات أصلية، فوثّق خطوات البناء وأي
متطلبات قائمة سماح لمدير الحزم (مثل `allow-build-scripts` في pnpm
- إذا كان Plugin الخاص بك يعتمد على وحدات أصلية، فوثّق خطوات البناء وأي
متطلبات قائمة سماح خاصة بمدير الحزم (مثل pnpm ‏`allow-build-scripts`
- `pnpm rebuild <package>`).
## ذو صلة
- [بناء Plugins](/ar/plugins/building-plugins) — البدء مع Plugins
- [بنية Plugin](/ar/plugins/architecture) — البنية الداخلية
- [معمارية Plugin](/ar/plugins/architecture) — المعمارية الداخلية
- [نظرة عامة على SDK](/ar/plugins/sdk-overview) — مرجع Plugin SDK

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

@ -1,37 +1,37 @@
---
read_when:
- أنت تضيف معالج إعداد إلى Plugin
- أنت تحتاج إلى فهم الفرق بين `setup-entry.ts` و`index.ts`
- أنت تعرّف مخططات تكوين Plugin أو بيانات `package.json` الوصفية الخاصة بـ openclaw
- تحتاج إلى فهم `setup-entry.ts` مقابل `index.ts`
- أنت تعرّف مخططات تكوين Plugin أو بيانات OpenClaw الوصفية في `package.json`
sidebarTitle: Setup and Config
summary: معالجات الإعداد، و`setup-entry.ts`، ومخططات التكوين، وبيانات `package.json` الوصفية
summary: معالجات الإعداد، `setup-entry.ts`، مخططات التكوين، وبيانات `package.json` الوصفية
title: إعداد Plugin والتكوين
x-i18n:
generated_at: "2026-04-23T07:30:19Z"
generated_at: "2026-04-23T14:01:10Z"
model: gpt-5.4
provider: openai
source_hash: ccdafb9a562353a7851fcd47bbc382961a449f5d645362c800f64c60579ce7b2
source_hash: 110cf9aa1bfaeb286d38963cfba2006502e853dd603a126d1c179cbc9b60aea1
source_path: plugins/sdk-setup.md
workflow: 15
---
# إعداد Plugin والتكوين
مرجع لتغليف Plugin (بيانات `package.json` الوصفية)، وmanifest
مرجع لتغليف Plugin (بيانات `package.json` الوصفية)، وملفات manifest
(`openclaw.plugin.json`)، وإدخالات الإعداد، ومخططات التكوين.
<Tip>
**هل تبحث عن شرح عملي؟** تغطي الأدلة الإرشادية التغليف ضمن السياق:
[Plugins القنوات](/ar/plugins/sdk-channel-plugins#step-1-package-and-manifest) و
[Plugins الموفّرين](/ar/plugins/sdk-provider-plugins#step-1-package-and-manifest).
[Channel Plugins](/ar/plugins/sdk-channel-plugins#step-1-package-and-manifest) و
[Provider Plugins](/ar/plugins/sdk-provider-plugins#step-1-package-and-manifest).
</Tip>
## بيانات الحزمة الوصفية
يحتاج ملف `package.json` لديك إلى حقل `openclaw` يُخبر نظام Plugin بما
يحتاج `package.json` الخاص بك إلى حقل `openclaw` يوضح لنظام Plugin ما الذي
يوفره Plugin الخاص بك:
**Plugin قناة:**
**Channel Plugin:**
```json
{
@ -50,7 +50,7 @@ x-i18n:
}
```
**Plugin موفّر / خط أساس نشر ClawHub:**
**Provider Plugin / خط أساس النشر في ClawHub:**
```json openclaw-clawhub-package.json
{
@ -71,47 +71,47 @@ x-i18n:
}
```
إذا نشرت Plugin خارجيًا على ClawHub، فستكون حقول `compat` و`build`
هذه مطلوبة. وتوجد مقتطفات النشر القياسية في
إذا نشرت Plugin خارجيًا على ClawHub، فإن حقلي `compat` و`build`
مطلوبان. وتوجد مقتطفات النشر القياسية في
`docs/snippets/plugin-publish/`.
### حقول `openclaw`
| الحقل | النوع | الوصف |
| ------------ | ---------- | --------------------------------------------------------------------------------------------------------------------------- |
| `extensions` | `string[]` | ملفات نقاط الإدخال (بالنسبة إلى جذر الحزمة) |
| `setupEntry` | `string` | إدخال خفيف خاص بالإعداد فقط (اختياري) |
| `channel` | `object` | بيانات وصفية لفهرس القنوات من أجل الإعداد، والمنتقي، والبدء السريع، وأسطح الحالة |
| `providers` | `string[]` | معرّفات الموفّرين التي يسجلها هذا Plugin |
| `install` | `object` | تلميحات التثبيت: `npmSpec`, `localPath`, `defaultChoice`, `minHostVersion`, `expectedIntegrity`, `allowInvalidConfigRecovery` |
| `startup` | `object` | علامات سلوك بدء التشغيل |
| الحقل | النوع | الوصف |
| ------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------ |
| `extensions` | `string[]` | ملفات نقطة الإدخال (نسبة إلى جذر الحزمة) |
| `setupEntry` | `string` | إدخال خفيف للإعداد فقط (اختياري) |
| `channel` | `object` | بيانات وصفية لفهرس القنوات لاستخدامها في الإعداد، والمنتقي، والبداية السريعة، وواجهات الحالة |
| `providers` | `string[]` | معرّفات Provider المسجّلة بواسطة هذا Plugin |
| `install` | `object` | تلميحات التثبيت: `npmSpec`, `localPath`, `defaultChoice`, `minHostVersion`, `expectedIntegrity`, `allowInvalidConfigRecovery` |
| `startup` | `object` | علامات سلوك بدء التشغيل |
### `openclaw.channel`
إن `openclaw.channel` هي بيانات وصفية خفيفة للحزمة لاكتشاف القنوات وأسطح
الإعداد قبل تحميل بيئة التشغيل.
الحقل `openclaw.channel` هو بيانات وصفية رخيصة على مستوى الحزمة لاكتشاف القنوات
وواجهات الإعداد قبل تحميل وقت التشغيل.
| الحقل | النوع | معناه |
| -------------------------------------- | ---------- | ----------------------------------------------------------------------------- |
| `id` | `string` | معرّف القناة القياسي. |
| `label` | `string` | التسمية الأساسية للقناة. |
| `selectionLabel` | `string` | تسمية المنتقي/الإعداد عندما ينبغي أن تختلف عن `label`. |
| `detailLabel` | `string` | تسمية تفصيلية ثانوية لكتالوجات القنوات الأغنى وأسطح الحالة. |
| `docsPath` | `string` | مسار المستندات لروابط الإعداد والاختيار. |
| `docsLabel` | `string` | تجاوز التسمية المستخدمة لروابط المستندات عندما ينبغي أن تختلف عن معرّف القناة. |
| `blurb` | `string` | وصف موجز للإعداد/الفهرس. |
| `order` | `number` | ترتيب الفرز في كتالوجات القنوات. |
| `aliases` | `string[]` | أسماء مستعارة إضافية للبحث عند اختيار القناة. |
| `preferOver` | `string[]` | معرّفات Plugins/قنوات أقل أولوية ينبغي أن تتقدم عليها هذه القناة. |
| `systemImage` | `string` | اسم أيقونة/system-image اختياري لكتالوجات واجهة مستخدم القنوات. |
| `selectionDocsPrefix` | `string` | نص بادئة قبل روابط المستندات في أسطح الاختيار. |
| `selectionDocsOmitLabel` | `boolean` | عرض مسار المستندات مباشرة بدلًا من رابط مستندات ذي تسمية في نص الاختيار. |
| `selectionExtras` | `string[]` | سلاسل قصيرة إضافية تُلحق في نص الاختيار. |
| `markdownCapable` | `boolean` | يعلّم القناة على أنها قادرة على Markdown لأغراض قرارات التنسيق الصادر. |
| `exposure` | `object` | عناصر تحكم في ظهور القناة للإعداد، والقوائم المُعدّة، وأسطح المستندات. |
| `quickstartAllowFrom` | `boolean` | يضم هذه القناة إلى تدفق إعداد `allowFrom` القياسي في البدء السريع. |
| `forceAccountBinding` | `boolean` | يفرض ربط حساب صريحًا حتى عند وجود حساب واحد فقط. |
| `preferSessionLookupForAnnounceTarget` | `boolean` | يفضّل البحث في الجلسة عند resolve لأهداف الإعلان لهذه القناة. |
| الحقل | النوع | معناه |
| -------------------------------------- | ---------- | ------------------------------------------------------------------------------ |
| `id` | `string` | معرّف القناة القياسي. |
| `label` | `string` | التسمية الأساسية للقناة. |
| `selectionLabel` | `string` | تسمية المنتقي/الإعداد عندما ينبغي أن تختلف عن `label`. |
| `detailLabel` | `string` | تسمية تفصيلية ثانوية لفهارس القنوات الأغنى وواجهات الحالة. |
| `docsPath` | `string` | مسار التوثيق لروابط الإعداد والاختيار. |
| `docsLabel` | `string` | تسمية بديلة مستخدمة لروابط التوثيق عندما ينبغي أن تختلف عن معرّف القناة. |
| `blurb` | `string` | وصف قصير للإعداد الأولي/الفهرس. |
| `order` | `number` | ترتيب الفرز في فهارس القنوات. |
| `aliases` | `string[]` | أسماء مستعارة إضافية للبحث عن القناة عند الاختيار. |
| `preferOver` | `string[]` | معرّفات Plugin/قنوات أقل أولوية يجب أن تتقدم عليها هذه القناة. |
| `systemImage` | `string` | اسم أيقونة/صورة نظام اختياري لفهارس واجهة القنوات. |
| `selectionDocsPrefix` | `string` | نص بادئة قبل روابط التوثيق في واجهات الاختيار. |
| `selectionDocsOmitLabel` | `boolean` | عرض مسار التوثيق مباشرةً بدلًا من رابط توثيق ذي تسمية في نص الاختيار. |
| `selectionExtras` | `string[]` | سلاسل قصيرة إضافية تُلحق في نص الاختيار. |
| `markdownCapable` | `boolean` | يحدد أن القناة قادرة على Markdown لقرارات التنسيق الصادر. |
| `exposure` | `object` | عناصر تحكم في ظهور القناة في الإعداد، والقوائم المضبوطة، وواجهات التوثيق. |
| `quickstartAllowFrom` | `boolean` | إدراج هذه القناة في تدفق البداية السريعة القياسي لـ `allowFrom`. |
| `forceAccountBinding` | `boolean` | فرض ربط صريح للحساب حتى عند وجود حساب واحد فقط. |
| `preferSessionLookupForAnnounceTarget` | `boolean` | تفضيل البحث في الجلسة عند حل أهداف الإعلان لهذه القناة. |
مثال:
@ -145,41 +145,41 @@ x-i18n:
يدعم `exposure` ما يلي:
- `configured`: تضمين القناة في أسطح القوائم المُعدّة/التي على نمط الحالة
- `configured`: تضمين القناة في واجهات القوائم المضبوطة/بنمط الحالة
- `setup`: تضمين القناة في منتقيات الإعداد/التكوين التفاعلية
- `docs`: تعليم القناة على أنها موجهة للعامة في أسطح المستندات/التنقل
- `docs`: تمييز القناة على أنها موجهة للعامة في واجهات التوثيق/التنقل
لا يزال `showConfigured` و`showInSetup` مدعومين كأسماء مستعارة قديمة. ويفضَّل
استخدام `exposure`.
ما زال `showConfigured` و`showInSetup` مدعومين كأسماء مستعارة قديمة. ويُفضَّل
`exposure`.
### `openclaw.install`
إن `openclaw.install` هي بيانات وصفية للحزمة، وليست بيانات وصفية للـ manifest.
الحقل `openclaw.install` هو بيانات وصفية للحزمة، وليس بيانات manifest وصفية.
| الحقل | النوع | معناه |
| ---------------------------- | -------------------- | -------------------------------------------------------------------------------- |
| `npmSpec` | `string` | مواصفة npm القياسية لتدفقات التثبيت/التحديث. |
| `localPath` | `string` | مسار التثبيت المحلي للتطوير أو التثبيت المضمّن. |
| `defaultChoice` | `"npm"` \| `"local"` | مصدر التثبيت المفضل عندما يكون كلاهما متاحًا. |
| `minHostVersion` | `string` | الحد الأدنى لإصدار OpenClaw المدعوم بالصورة `>=x.y.z`. |
| `expectedIntegrity` | `string` | سلسلة سلامة npm dist المتوقعة، وعادة تكون `sha512-...`، للتثبيتات المثبتة. |
| `allowInvalidConfigRecovery` | `boolean` | يسمح لتدفقات إعادة تثبيت Plugin المضمّن بالتعافي من حالات فشل محددة ناتجة عن تكوين قديم. |
| الحقل | النوع | معناه |
| ---------------------------- | -------------------- | ----------------------------------------------------------------------------------- |
| `npmSpec` | `string` | مواصفة npm القياسية لتدفقات التثبيت/التحديث. |
| `localPath` | `string` | مسار تثبيت محلي للتطوير أو مضمّن. |
| `defaultChoice` | `"npm"` \| `"local"` | مصدر التثبيت المفضل عند توفر الاثنين. |
| `minHostVersion` | `string` | الحد الأدنى لإصدار OpenClaw المدعوم بصيغة `>=x.y.z`. |
| `expectedIntegrity` | `string` | سلسلة سلامة npm dist المتوقعة، وعادةً `sha512-...`، لعمليات التثبيت المثبتة. |
| `allowInvalidConfigRecovery` | `boolean` | يتيح لتدفقات إعادة تثبيت Plugin المضمّن التعافي من بعض حالات فشل التكوين القديم المحددة. |
يستخدم onboarding التفاعلي أيضًا `openclaw.install` في أسطح
التثبيت عند الطلب. وإذا كان Plugin الخاص بك يكشف اختيارات مصادقة الموفّر أو بيانات
إعداد/فهرسة القنوات قبل تحميل بيئة التشغيل، فيمكن لـ onboarding إظهار ذلك
الاختيار، ثم طلب npm أو التثبيت المحلي، ثم تثبيت Plugin أو تفعيله، ثم متابعة
التدفق المحدد. وتتطلب اختيارات onboarding الخاصة بـ npm بيانات وصفية موثوقة للفهرس تحتوي على
`npmSpec` بإصدار دقيق و`expectedIntegrity`؛ ولا تُعرض أسماء الحزم غير المثبتة
والـ dist-tags من أجل تثبيتات onboarding التلقائية. أبقِ البيانات الوصفية الخاصة
بـ "ما الذي يجب عرضه" في `openclaw.plugin.json` والبيانات الوصفية الخاصة
بـ "كيف يتم تثبيته" في `package.json`.
يستخدم الإعداد الأولي التفاعلي أيضًا `openclaw.install` لواجهات
التثبيت عند الطلب. إذا كان Plugin الخاص بك يعرض خيارات مصادقة Provider أو
بيانات وصفية لإعداد/فهرسة القنوات قبل تحميل وقت التشغيل، فيمكن للإعداد الأولي
عرض هذا الخيار، والمطالبة بالاختيار بين تثبيت npm أو محلي، ثم تثبيت أو تمكين
Plugin، ثم متابعة التدفق المحدد. تتطلب خيارات إعداد npm بيانات وصفية موثوقة
من الفهرس مع `npmSpec` في السجل؛ أما الإصدارات الدقيقة و`expectedIntegrity`
فهما دبابيس اختيارية. إذا كانت `expectedIntegrity` موجودة، فإن تدفقات
التثبيت/التحديث تفرضها. احتفظ ببيانات "ما الذي يجب عرضه" الوصفية في
`openclaw.plugin.json` وبيانات "كيفية تثبيته" الوصفية في `package.json`.
إذا تم تعيين `minHostVersion`، فإن كلًا من التثبيت وتحميل سجل manifest
يفرضانه. وتتجاوز المضيفات الأقدم Plugin؛ كما تُرفض سلاسل الإصدارات غير الصالحة.
إذا ضُبط `minHostVersion`، فإن التثبيت وتحميل سجل manifest يفرضان كليهما
هذا الشرط. وتتخطى المضيفات الأقدم Plugin؛ كما تُرفض سلاسل الإصدارات غير الصالحة.
بالنسبة إلى تثبيتات npm المثبتة، احتفظ بالإصدار الدقيق في `npmSpec` وأضف
سلامة العنصر المتوقعة:
سلامة الأثر المتوقعة:
```json
{
@ -193,15 +193,15 @@ x-i18n:
}
```
إن `allowInvalidConfigRecovery` ليس تجاوزًا عامًا للتكوينات المعطلة. بل هو
مخصص فقط لتعافٍ ضيق خاص بالـ Plugin المضمّن، حتى يتمكن إعادة التثبيت/الإعداد من إصلاح
مخلفات ترقية معروفة مثل مسار Plugin مضمّن مفقود أو إدخال `channels.<id>`
قديم يعود إلى Plugin نفسه. وإذا كان التكوين معطّلًا لأسباب غير مرتبطة، فإن التثبيت
سيفشل بشكل مغلق وسيخبر المشغّل بتشغيل `openclaw doctor --fix`.
لا يُعد `allowInvalidConfigRecovery` تجاوزًا عامًا للتكوينات المعطوبة. بل هو
للتعافي المحدود فقط في حالة Plugin المضمّن، بحيث يمكن لإعادة التثبيت/الإعداد
إصلاح بقايا ترقية معروفة مثل غياب مسار Plugin مضمّن أو إدخال قديم في
`channels.<id>` لذلك Plugin نفسه. إذا كان التكوين معطوبًا لأسباب غير ذات صلة،
يفشل التثبيت بشكل مغلق ويطلب من المشغّل تشغيل `openclaw doctor --fix`.
### تأجيل التحميل الكامل
يمكن لـ Plugins القنوات الاشتراك في التحميل المؤجل باستخدام:
يمكن لـ Channel Plugins اختيار التحميل المؤجل باستخدام:
```json
{
@ -215,25 +215,26 @@ x-i18n:
}
```
عند التفعيل، يحمّل OpenClaw `setupEntry` فقط خلال مرحلة بدء التشغيل السابقة لـ listen،
حتى بالنسبة إلى القنوات المُعدّة بالفعل. ويتم تحميل الإدخال الكامل بعد أن
يبدأ gateway الاستماع.
عند التمكين، يحمّل OpenClaw فقط `setupEntry` خلال مرحلة بدء التشغيل السابقة
للاستماع، حتى بالنسبة إلى القنوات المضبوطة بالفعل. ويتم تحميل الإدخال الكامل بعد
أن يبدأ Gateway الاستماع.
<Warning>
فعّل التحميل المؤجل فقط عندما يسجل `setupEntry` لديك كل ما يحتاجه
gateway قبل أن يبدأ الاستماع (تسجيل القناة، ومسارات HTTP، وطرائق gateway). وإذا كان الإدخال الكامل يملك Capabilities مطلوبة عند بدء التشغيل، فأبقِ
السلوك الافتراضي.
فعّل التحميل المؤجل فقط عندما يسجل `setupEntry` كل ما يحتاجه
Gateway قبل أن يبدأ الاستماع (تسجيل القناة، ومسارات HTTP، وطرائق Gateway).
إذا كان الإدخال الكامل يملك قدرات بدء تشغيل مطلوبة، فاحتفظ
بالسلوك الافتراضي.
</Warning>
إذا كان إدخال الإعداد/الإدخال الكامل لديك يسجل طرائق Gateway RPC، فاحتفظ بها على
بادئة خاصة بالـ Plugin. وتبقى مساحات أسماء الإدارة الأساسية المحجوزة (`config.*`,
`exec.approvals.*`, `wizard.*`, `update.*`) مملوكة لـ core وتُحل دائمًا
إلى `operator.admin`.
إذا كان إدخال الإعداد/الإدخال الكامل يسجل طرائق Gateway RPC، فأبقها على
بادئة خاصة بـ Plugin. تظل مساحات أسماء الإدارة الأساسية المحجوزة (`config.*`,
`exec.approvals.*`, `wizard.*`, `update.*`) مملوكة للنواة وتُحل دائمًا إلى
`operator.admin`.
## Plugin Manifest
## manifest الخاص بـ Plugin
يجب أن يشحن كل Plugin أصلي ملف `openclaw.plugin.json` في جذر الحزمة.
يستخدم OpenClaw هذا للتحقق من التكوين من دون تنفيذ شيفرة Plugin.
يجب أن يحتوي كل Plugin أصلي على ملف `openclaw.plugin.json` في جذر الحزمة.
يستخدم OpenClaw هذا للتحقق من التكوين من دون تنفيذ كود Plugin.
```json
{
@ -253,7 +254,7 @@ x-i18n:
}
```
بالنسبة إلى Plugins القنوات، أضف `kind` و`channels`:
بالنسبة إلى Channel Plugins، أضف `kind` و`channels`:
```json
{
@ -268,7 +269,7 @@ x-i18n:
}
```
حتى Plugins التي لا تحتوي على تكوين يجب أن تشحن مخططًا. ويكون المخطط الفارغ صالحًا:
حتى Plugins التي لا تحتوي على تكوين يجب أن تشحن مخططًا. والمخطط الفارغ صالح:
```json
{
@ -282,22 +283,22 @@ x-i18n:
راجع [Plugin Manifest](/ar/plugins/manifest) للحصول على المرجع الكامل للمخطط.
## النشر على ClawHub
## النشر إلى ClawHub
بالنسبة إلى حزم Plugins، استخدم أمر ClawHub الخاص بالحزمة:
بالنسبة إلى حزم Plugin، استخدم أمر ClawHub الخاص بالحزمة:
```bash
clawhub package publish your-org/your-plugin --dry-run
clawhub package publish your-org/your-plugin
```
إن الاسم المستعار القديم للنشر الخاص بالـ Skills فقط مخصص للـ Skills. أما حزم Plugins فيجب
أن تستخدم دائمًا `clawhub package publish`.
الاسم المستعار القديم للنشر الخاص بـ Skills هو للمهارات فقط. ويجب أن تستخدم حزم Plugin
دائمًا `clawhub package publish`.
## إدخال الإعداد
إن الملف `setup-entry.ts` هو بديل خفيف لـ `index.ts` يقوم
OpenClaw بتحميله عندما يحتاج فقط إلى أسطح الإعداد (onboarding، وإصلاح التكوين،
ملف `setup-entry.ts` هو بديل خفيف لـ `index.ts` يقوم
OpenClaw بتحميله عندما يحتاج فقط إلى واجهات الإعداد (الإعداد الأولي، وإصلاح التكوين،
وفحص القنوات المعطلة).
```typescript
@ -308,82 +309,81 @@ import { myChannelPlugin } from "./src/channel.js";
export default defineSetupPluginEntry(myChannelPlugin);
```
يتجنب هذا تحميل شيفرة بيئة تشغيل ثقيلة (مكتبات التشفير، وتسجيلات CLI،
يؤدي هذا إلى تجنب تحميل كود وقت تشغيل ثقيل (مكتبات التشفير، وتسجيلات CLI،
والخدمات الخلفية) أثناء تدفقات الإعداد.
يمكن لقنوات مساحة العمل المضمّنة التي تحتفظ بعمليات تصدير آمنة للإعداد في وحدات جانبية
يمكن لقنوات مساحة العمل المضمنة التي تحتفظ بصادرات آمنة للإعداد في وحدات sidecar
استخدام `defineBundledChannelSetupEntry(...)` من
`openclaw/plugin-sdk/channel-entry-contract` بدلًا من
`defineSetupPluginEntry(...)`. يدعم هذا العقد المضمّن أيضًا export اختياريًا باسم
`runtime` بحيث يبقى توصيل بيئة التشغيل وقت الإعداد خفيفًا وصريحًا.
`defineSetupPluginEntry(...)`. يدعم هذا العقد المضمّن أيضًا تصديرًا اختياريًا
باسم `runtime` حتى يبقى ربط وقت التشغيل في وقت الإعداد خفيفًا وصريحًا.
**متى يستخدم OpenClaw `setupEntry` بدلًا من الإدخال الكامل:**
- تكون القناة معطلة لكنها تحتاج إلى أسطح إعداد/onboarding
- تكون القناة مفعلة لكنها غير مضبوطة
- تكون القناة معطلة لكنها تحتاج إلى واجهات إعداد/تهيئة أولية
- تكون القناة مفعلة ولكن غير مضبوطة
- يكون التحميل المؤجل مفعّلًا (`deferConfiguredChannelFullLoadUntilAfterListen`)
**ما الذي يجب أن يسجله `setupEntry`:**
- كائن Plugin القناة (عبر `defineSetupPluginEntry`)
- أي مسارات HTTP مطلوبة قبل أن يبدأ gateway الاستماع
- أي طرائق gateway مطلوبة أثناء بدء التشغيل
- كائن Channel Plugin (عبر `defineSetupPluginEntry`)
- أي مسارات HTTP مطلوبة قبل أن يبدأ Gateway الاستماع
- أي طرائق Gateway مطلوبة أثناء بدء التشغيل
يجب أن تتجنب طرائق Gateway الخاصة ببدء التشغيل هذه أيضًا مساحات أسماء الإدارة الأساسية
المحجوزة مثل `config.*` أو `update.*`.
ويجب على طرائق Gateway الخاصة ببدء التشغيل هذه أيضًا تجنب
مساحات أسماء الإدارة الأساسية المحجوزة مثل `config.*` أو `update.*`.
**ما الذي لا ينبغي أن يتضمنه `setupEntry`:**
**ما الذي يجب ألا يتضمنه `setupEntry`:**
- تسجيلات CLI
- الخدمات الخلفية
- عمليات استيراد بيئة تشغيل ثقيلة (التشفير، SDKs)
- استيرادات وقت تشغيل ثقيلة (التشفير، SDKs)
- طرائق Gateway المطلوبة فقط بعد بدء التشغيل
### عمليات استيراد ضيقة لمساعدات الإعداد
### استيرادات مساعدات الإعداد الضيقة
بالنسبة إلى مسارات الإعداد الساخنة فقط، فضّل وصلات مساعدات الإعداد الضيقة بدلًا من واجهة
`plugin-sdk/setup` الأشمل عندما تحتاج فقط إلى جزء من سطح الإعداد:
بالنسبة إلى المسارات الساخنة الخاصة بالإعداد فقط، فضّل واجهات مساعدات الإعداد الضيقة بدلًا من
المظلة الأوسع `plugin-sdk/setup` عندما تحتاج فقط إلى جزء من واجهة الإعداد:
| مسار الاستيراد | استخدمه من أجل | أهم الصادرات |
| ---------------------------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `plugin-sdk/setup-runtime` | مساعدات بيئة التشغيل وقت الإعداد التي تظل متاحة في `setupEntry` / بدء تشغيل القناة المؤجل | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` |
| `plugin-sdk/setup-adapter-runtime` | محولات إعداد الحسابات الواعية بالبيئة | `createEnvPatchedAccountSetupAdapter` |
| `plugin-sdk/setup-tools` | مساعدات CLI/الأرشيف/المستندات الخاصة بالإعداد/التثبيت | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
| مسار الاستيراد | استخدمه من أجل | الصادرات الأساسية |
| ---------------------------------- | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `plugin-sdk/setup-runtime` | مساعدات وقت التشغيل في وقت الإعداد التي تبقى متاحة في `setupEntry` / بدء تشغيل القناة المؤجل | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` |
| `plugin-sdk/setup-adapter-runtime` | مهايئات إعداد الحسابات الواعية بالبيئة | `createEnvPatchedAccountSetupAdapter` |
| `plugin-sdk/setup-tools` | مساعدات CLI/الأرشيف/التوثيق الخاصة بالإعداد والتثبيت | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
استخدم وصلة `plugin-sdk/setup` الأعرض عندما تريد صندوق أدوات الإعداد
المشترك الكامل، بما في ذلك مساعدات ترقيع التكوين مثل
استخدم الواجهة الأوسع `plugin-sdk/setup` عندما تريد صندوق أدوات الإعداد
المشترك الكامل، بما في ذلك مساعدات patch الخاصة بالتكوين مثل
`moveSingleAccountChannelSectionToDefaultAccount(...)`.
تظل محولات ترقيع الإعداد آمنة للاستيراد في المسار الساخن. ويكون البحث عن سطح عقد
الترقية للحساب الواحد في الحِزم المضمّنة كسولًا، لذا فإن استيراد
`plugin-sdk/setup-runtime` لا يحمّل اكتشاف سطح العقد المضمّن مسبقًا
قبل استخدام المحول فعليًا.
تبقى مهايئات patch الخاصة بالإعداد آمنة للاستيراد ضمن المسار الساخن. البحث الخاص بها
عن سطح عقدة الترقية للحساب الفردي في القنوات المضمنة يكون كسولًا، لذا فإن استيراد
`plugin-sdk/setup-runtime` لا يحمّل مسبقًا اكتشاف سطح العقدة المضمنة قبل
استخدام المهايئ فعليًا.
### ترقية الحساب الواحد المملوكة للقناة
### ترقية الحساب الفردي المملوكة للقناة
عندما تنتقل قناة من تكوين علوي لحساب واحد إلى
`channels.<id>.accounts.*`، فإن السلوك المشترك الافتراضي هو نقل القيم ذات
النطاق الحسابي المُرقّاة إلى `accounts.default`.
عندما تقوم قناة بترقية تكوينها من تكوين علوي لحساب واحد إلى
`channels.<id>.accounts.*`، يكون السلوك المشترك الافتراضي هو نقل القيم
المخصصة لنطاق الحساب التي جرت ترقيتها إلى `accounts.default`.
يمكن للقنوات المضمّنة تضييق هذه الترقية أو تجاوزها عبر سطح عقد
الإعداد الخاص بها:
يمكن للقنوات المضمنة تضييق هذه الترقية أو تجاوزها عبر سطح عقدة الإعداد الخاص بها:
- `singleAccountKeysToMove`: مفاتيح علوية إضافية ينبغي نقلها إلى
الحساب المُرقّى
- `singleAccountKeysToMove`: مفاتيح إضافية من المستوى الأعلى يجب نقلها إلى
الحساب الذي تمت ترقيته
- `namedAccountPromotionKeys`: عندما تكون الحسابات المسماة موجودة بالفعل، لا تُنقل
إلى الحساب المُرقّى إلا هذه المفاتيح؛ أما مفاتيح السياسة/التسليم المشتركة
إلى الحساب الذي تمت ترقيته إلا هذه المفاتيح؛ أما مفاتيح السياسة/التسليم المشتركة
فتبقى عند جذر القناة
- `resolveSingleAccountPromotionTarget(...)`: اختيار الحساب الموجود الذي
يستقبل القيم المُرقّاة
سيتلقى القيم المرقاة
يمثل Matrix المثال المضمّن الحالي. فإذا كان هناك بالفعل حساب Matrix
مسمى واحد فقط، أو إذا كانت `defaultAccount` تشير إلى مفتاح غير قياسي موجود
تُعد Matrix المثال المضمّن الحالي. إذا كان هناك حساب Matrix مسمى واحد فقط
موجودًا بالفعل، أو إذا كانت `defaultAccount` تشير إلى مفتاح موجود غير قياسي
مثل `Ops`، فإن الترقية تحافظ على ذلك الحساب بدلًا من إنشاء إدخال جديد
باسم `accounts.default`.
`accounts.default`.
## مخطط التكوين
يتم التحقق من تكوين Plugin وفق JSON Schema الموجود في manifest لديك. يقوم المستخدمون
يتم التحقق من تكوين Plugin مقابل JSON Schema الموجود في manifest الخاص بك. ويقوم المستخدمون
بتكوين Plugins عبر:
```json5
@ -400,9 +400,9 @@ export default defineSetupPluginEntry(myChannelPlugin);
}
```
يتلقى Plugin الخاص بك هذا التكوين على شكل `api.pluginConfig` أثناء التسجيل.
يتلقى Plugin هذا التكوين على هيئة `api.pluginConfig` أثناء التسجيل.
أما بالنسبة إلى التكوين الخاص بالقناة، فاستخدم قسم تكوين القناة بدلًا من ذلك:
وبالنسبة إلى التكوين الخاص بالقناة، استخدم قسم تكوين القناة بدلًا من ذلك:
```json5
{
@ -415,7 +415,7 @@ export default defineSetupPluginEntry(myChannelPlugin);
}
```
### بناء مخططات تكوين القنوات
### بناء مخططات تكوين القناة
استخدم `buildChannelConfigSchema` من `openclaw/plugin-sdk/core` لتحويل
مخطط Zod إلى غلاف `ChannelConfigSchema` الذي يتحقق منه OpenClaw:
@ -436,8 +436,8 @@ const configSchema = buildChannelConfigSchema(accountSchema);
## معالجات الإعداد
يمكن لـ Plugins القنوات توفير معالجات إعداد تفاعلية للأمر `openclaw onboard`.
ويكون المعالج كائن `ChannelSetupWizard` على `ChannelPlugin`:
يمكن لـ Channel Plugins توفير معالجات إعداد تفاعلية لأمر `openclaw onboard`.
المعالج عبارة عن كائن `ChannelSetupWizard` على `ChannelPlugin`:
```typescript
import type { ChannelSetupWizard } from "openclaw/plugin-sdk/channel-setup";
@ -470,23 +470,23 @@ const setupWizard: ChannelSetupWizard = {
};
```
يدعم النوع `ChannelSetupWizard` الحقول `credentials` و`textInputs`،
و`dmPolicy` و`allowFrom` و`groupAccess` و`prepare` و`finalize` وغير ذلك.
راجع حزم Plugins المضمّنة (مثل Plugin Discord في `src/channel.setup.ts`) للحصول على
يدعم النوع `ChannelSetupWizard` عناصر مثل `credentials` و`textInputs` و
`dmPolicy` و`allowFrom` و`groupAccess` و`prepare` و`finalize` وغير ذلك.
راجع حزم Plugin المضمنة (على سبيل المثال Discord plugin في `src/channel.setup.ts`) للاطلاع على
أمثلة كاملة.
بالنسبة إلى مطالبات قائمة السماح للرسائل المباشرة التي تحتاج فقط إلى تدفق
`note -> prompt -> parse -> merge -> patch` القياسي، ففضّل مساعدات الإعداد
المشتركة من `openclaw/plugin-sdk/setup`: وهي `createPromptParsedAllowFromForAccount(...)`,
`note -> prompt -> parse -> merge -> patch` القياسي، فضّل مساعدات الإعداد
المشتركة من `openclaw/plugin-sdk/setup`: `createPromptParsedAllowFromForAccount(...)`,
و`createTopLevelChannelParsedAllowFromPrompt(...)`، و
`createNestedChannelParsedAllowFromPrompt(...)`.
أما بالنسبة إلى كتل حالة إعداد القناة التي تختلف فقط في التسميات والدرجات والأسطر
الإضافية الاختيارية، ففضّل `createStandardChannelSetupStatus(...)` من
`openclaw/plugin-sdk/setup` بدلًا من بناء كائن `status` نفسه يدويًا في
كل Plugin.
وبالنسبة إلى كتل حالة إعداد القناة التي لا تختلف إلا في التسميات والدرجات
والأسطر الإضافية الاختيارية، فضّل `createStandardChannelSetupStatus(...)` من
`openclaw/plugin-sdk/setup` بدلًا من كتابة كائن `status` نفسه يدويًا
في كل Plugin.
وبالنسبة إلى أسطح الإعداد الاختيارية التي ينبغي أن تظهر فقط في سياقات معينة، فاستخدم
وبالنسبة إلى واجهات الإعداد الاختيارية التي ينبغي أن تظهر فقط في سياقات معينة، استخدم
`createOptionalChannelSetupSurface` من `openclaw/plugin-sdk/channel-setup`:
```typescript
@ -501,32 +501,32 @@ const setupSurface = createOptionalChannelSetupSurface({
// Returns { setupAdapter, setupWizard }
```
يكشف `plugin-sdk/channel-setup` أيضًا البانِيَين ذوي المستوى الأدنى
كما يعرّض `plugin-sdk/channel-setup` أيضًا البنّاءين منخفضي المستوى
`createOptionalChannelSetupAdapter(...)` و
`createOptionalChannelSetupWizard(...)` عندما تحتاج فقط إلى نصف واحد من
سطح التثبيت الاختياري ذاك.
واجهة التثبيت الاختيارية تلك.
يفشل المحول/المعالج الاختياري المُولَّد بشكل مغلق عند كتابات التكوين الحقيقية. وهو
يعيد استخدام رسالة واحدة تفيد بوجوب التثبيت عبر `validateInput`,
و`applyAccountConfig`، و`finalize`، ويُلحق رابط مستندات عندما يكون `docsPath`
محددًا.
تفشل المهايئات/المعالجات الاختيارية المولدة بشكل مغلق عند الكتابات الفعلية للتكوين. وهي
تعيد استخدام رسالة واحدة تفيد بأن التثبيت مطلوب عبر `validateInput`,
و`applyAccountConfig`، و`finalize`، وتُلحق رابط توثيق عندما تكون `docsPath`
مضبوطة.
بالنسبة إلى واجهات الإعداد المعتمدة على الملفات التنفيذية، ففضّل المساعدات المشتركة المفوَّضة بدلًا من
نسخ الغراء نفسه الخاص بالملف التنفيذي/الحالة داخل كل قناة:
وبالنسبة إلى واجهات الإعداد المعتمدة على binary، فضّل المساعدات المشتركة المفوضة بدلًا من
نسخ المنطق نفسه الخاص بالثنائيات/الحالة في كل قناة:
- `createDetectedBinaryStatus(...)` لكتل الحالة التي تختلف فقط في التسميات،
والتلميحات، والدرجات، واكتشاف الملف التنفيذي
- `createDetectedBinaryStatus(...)` لكتل الحالة التي لا تختلف إلا في التسميات،
والتلميحات، والدرجات، واكتشاف binary
- `createCliPathTextInput(...)` لمدخلات النص المعتمدة على المسار
- `createDelegatedSetupWizardStatusResolvers(...)`,
و`createDelegatedPrepare(...)`, و`createDelegatedFinalize(...)`, و
`createDelegatedResolveConfigured(...)` عندما يحتاج `setupEntry` إلى التمرير إلى
معالج كامل أثقل بشكل كسول
`createDelegatedResolveConfigured(...)` عندما يحتاج `setupEntry` إلى
التفويض كسولًا إلى معالج كامل أثقل
- `createDelegatedTextInputShouldPrompt(...)` عندما يحتاج `setupEntry` فقط إلى
تفويض قرار `textInputs[*].shouldPrompt`
## النشر والتثبيت
**Plugins الخارجية:** انشر إلى [ClawHub](/ar/tools/clawhub) أو npm، ثم ثبّت باستخدام:
**Plugins الخارجية:** انشر إلى [ClawHub](/ar/tools/clawhub) أو npm، ثم ثبّت:
```bash
openclaw plugins install @myorg/openclaw-my-plugin
@ -536,17 +536,17 @@ openclaw plugins install @myorg/openclaw-my-plugin
فرض ClawHub صراحةً:
```bash
openclaw plugins install clawhub:@myorg/openclaw-my-plugin # ClawHub فقط
openclaw plugins install clawhub:@myorg/openclaw-my-plugin # ClawHub only
```
لا يوجد تجاوز مطابق باسم `npm:`. استخدم مواصفة حزمة npm العادية عندما
تريد مسار npm بعد رجوع ClawHub الاحتياطي:
لا يوجد تجاوز مطابق لـ `npm:`. استخدم مواصفة حزمة npm العادية عندما
تريد مسار npm بعد الرجوع من ClawHub:
```bash
openclaw plugins install @myorg/openclaw-my-plugin
```
**Plugins داخل المستودع:** ضعها تحت شجرة مساحة عمل Plugins المضمّنة وسيتم
**Plugins داخل المستودع:** ضعها ضمن شجرة مساحة عمل Plugin المضمنة وسيتم
اكتشافها تلقائيًا أثناء البناء.
**يمكن للمستخدمين التثبيت عبر:**
@ -557,17 +557,18 @@ openclaw plugins install <package-name>
<Info>
بالنسبة إلى التثبيتات القادمة من npm، يشغّل `openclaw plugins install`
الأمر `npm install --ignore-scripts` (من دون lifecycle scripts). أبقِ أشجار
تبعيات Plugin على JS/TS خالصة وتجنب الحزم التي تتطلب عمليات بناء في `postinstall`.
الأمر `npm install --ignore-scripts` (من دون lifecycle scripts). حافظ على شجرة
تبعيات Plugin بلغة JS/TS خالصة وتجنب الحزم التي تتطلب بناء `postinstall`.
</Info>
تشكّل Plugins المضمّنة المملوكة لـ OpenClaw الاستثناء الوحيد لإصلاحات بدء التشغيل: فعندما
يرى تثبيت مجمّع أن أحدها مفعّل عبر تكوين Plugin، أو تكوين قناة قديم، أو manifest
المضمّن المفعّل افتراضيًا، فإن بدء التشغيل يثبّت تبعيات بيئة التشغيل المفقودة لذلك Plugin قبل الاستيراد. لا ينبغي للـ Plugins الخارجية الاعتماد على
تثبيتات بدء التشغيل؛ واصل استخدام مثبّت Plugin الصريح.
تُعد Plugins المضمنة المملوكة لـ OpenClaw هي الاستثناء الوحيد لإصلاح بدء التشغيل: عندما
يرى التثبيت المجمّع أحدها مفعّلًا عبر تكوين Plugin، أو تكوين قناة قديم، أو
manifest المضمّن الافتراضي المفعّل الخاص به، فإن بدء التشغيل يثبت تبعيات وقت
التشغيل المفقودة لذلك Plugin قبل الاستيراد. يجب ألا تعتمد Plugins الخارجية على
عمليات تثبيت وقت التشغيل؛ واصل استخدام مثبّت Plugin الصريح.
## ذو صلة
- [نقاط إدخال SDK](/ar/plugins/sdk-entrypoints) -- ‏`definePluginEntry` و`defineChannelPluginEntry`
- [نقاط إدخال SDK](/ar/plugins/sdk-entrypoints) -- `definePluginEntry` و`defineChannelPluginEntry`
- [Plugin Manifest](/ar/plugins/manifest) -- المرجع الكامل لمخطط manifest
- [بناء Plugins](/ar/plugins/building-plugins) -- دليل البدء خطوة بخطوة
- [بناء Plugins](/ar/plugins/building-plugins) -- دليل خطوة بخطوة للبدء

130
docs/ar/providers/anthropic.md
View File

@ -4,42 +4,42 @@ read_when:
summary: استخدم Anthropic Claude عبر مفاتيح API أو Claude CLI في OpenClaw
title: Anthropic
x-i18n:
generated_at: "2026-04-23T07:30:17Z"
generated_at: "2026-04-23T14:01:26Z"
model: gpt-5.4
provider: openai
source_hash: 02e99e31bf58d08a18f526281b3bf5c3a5a96b2ff342adf3a6a193a076147a03
source_hash: e1e95c84a43b083d12558d8b8c86d36b79e7ef15e4ad7e96a84b2d0e1ea36585
source_path: providers/anthropic.md
workflow: 15
---
# Anthropic (Claude)
تطوّر Anthropic عائلة نماذج **Claude**. ويدعم OpenClaw مساري مصادقة:
تطوّر Anthropic عائلة نماذج **Claude**. يدعم OpenClaw مسارين للمصادقة:
- **مفتاح API** — وصول مباشر إلى Anthropic API مع فوترة حسب الاستخدام (نماذج `anthropic/*`)
- **مفتاح API** — وصول مباشر إلى Anthropic API مع فوترة حسب الاستخدام (لنماذج `anthropic/*`)
- **Claude CLI** — إعادة استخدام تسجيل دخول Claude CLI موجود على المضيف نفسه
<Warning>
أخبرنا موظفو Anthropic أن استخدام Claude CLI على نمط OpenClaw مسموح به مجددًا، لذلك
أخبرنا فريق Anthropic أن استخدام Claude CLI بأسلوب OpenClaw مسموح به مرة أخرى، لذلك
يتعامل OpenClaw مع إعادة استخدام Claude CLI واستخدام `claude -p` على أنهما معتمدان ما لم
تنشر Anthropic سياسة جديدة.
أما بالنسبة إلى مضيفي Gateway طويلَي العمر، فما تزال مفاتيح Anthropic API هي المسار الإنتاجي
وبالنسبة لمضيفي Gateway طويلة العمر، تظل مفاتيح Anthropic API هي المسار الإنتاجي
الأوضح والأكثر قابلية للتنبؤ.
الوثائق العامة الحالية لـ Anthropic:
الوثائق العامة الحالية من Anthropic:
- [مرجع Claude Code CLI](https://code.claude.com/docs/en/cli-reference)
- [نظرة عامة على Claude Agent SDK](https://platform.claude.com/docs/en/agent-sdk/overview)
- [استخدام Claude Code مع خطة Pro أو Max](https://support.claude.com/en/articles/11145838-using-claude-code-with-your-pro-or-max-plan)
- [استخدام Claude Code مع خطة Team أو Enterprise](https://support.anthropic.com/en/articles/11845131-using-claude-code-with-your-team-or-enterprise-plan/)
- [استخدام Claude Code مع خطة Pro أو Max الخاصة بك](https://support.claude.com/en/articles/11145838-using-claude-code-with-your-pro-or-max-plan)
- [استخدام Claude Code مع خطة Team أو Enterprise الخاصة بك](https://support.anthropic.com/en/articles/11845131-using-claude-code-with-your-team-or-enterprise-plan/)
</Warning>
## البدء
<Tabs>
<Tab title="API key">
<Tab title="مفتاح API">
**الأفضل لـ:** وصول API القياسي والفوترة حسب الاستخدام.
<Steps>
@ -49,7 +49,7 @@ x-i18n:
<Step title="شغّل الإعداد الأولي">
```bash
openclaw onboard
# اختر: Anthropic API key
# choose: Anthropic API key
```
أو مرّر المفتاح مباشرة:
@ -65,7 +65,7 @@ x-i18n:
</Step>
</Steps>
### مثال على الإعدادات
### مثال على التكوين
```json5
{
@ -80,7 +80,7 @@ x-i18n:
**الأفضل لـ:** إعادة استخدام تسجيل دخول Claude CLI موجود من دون مفتاح API منفصل.
<Steps>
<Step title="تأكد من أن Claude CLI مثبت ومُسجَّل الدخول">
<Step title="تأكد من أن Claude CLI مثبت وتم تسجيل الدخول فيه">
تحقق باستخدام:
```bash
@ -90,7 +90,7 @@ x-i18n:
<Step title="شغّل الإعداد الأولي">
```bash
openclaw onboard
# اختر: Claude CLI
# choose: Claude CLI
```
يكتشف OpenClaw بيانات اعتماد Claude CLI الموجودة ويعيد استخدامها.
@ -103,19 +103,19 @@ x-i18n:
</Steps>
<Note>
توجد تفاصيل الإعداد وبيئة التشغيل للواجهة الخلفية Claude CLI في [الواجهات الخلفية لـ CLI](/ar/gateway/cli-backends).
تفاصيل الإعداد ووقت التشغيل لواجهة Claude CLI الخلفية موجودة في [واجهات CLI الخلفية](/ar/gateway/cli-backends).
</Note>
<Tip>
إذا كنت تريد أوضح مسار للفوترة، فاستخدم مفتاح Anthropic API بدلًا من ذلك. كما يدعم OpenClaw أيضًا خيارات بنمط الاشتراك من [OpenAI Codex](/ar/providers/openai) و[Qwen Cloud](/ar/providers/qwen) و[MiniMax](/ar/providers/minimax) و[Z.AI / GLM](/ar/providers/glm).
إذا كنت تريد مسار فوترة أوضح، فاستخدم مفتاح Anthropic API بدلًا من ذلك. يدعم OpenClaw أيضًا خيارات بأسلوب الاشتراك من [OpenAI Codex](/ar/providers/openai) و[Qwen Cloud](/ar/providers/qwen) و[MiniMax](/ar/providers/minimax) و[Z.AI / GLM](/ar/providers/glm).
</Tip>
</Tab>
</Tabs>
## افتراضات التفكير (Claude 4.6)
## الإعدادات الافتراضية للتفكير (Claude 4.6)
تستخدم نماذج Claude 4.6 وضع التفكير `adaptive` افتراضيًا في OpenClaw عندما لا يكون هناك مستوى تفكير صريح مضبوط.
تستخدم نماذج Claude 4.6 افتراضيًا التفكير `adaptive` في OpenClaw عندما لا يتم تعيين مستوى تفكير صريح.
يمكنك التجاوز لكل رسالة باستخدام `/think:<level>` أو في معاملات النموذج:
@ -136,18 +136,18 @@ x-i18n:
<Note>
وثائق Anthropic ذات الصلة:
- [التفكير التكيفي](https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking)
- [التفكير الممتد](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)
- [التفكير الموسّع](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)
</Note>
## Prompt caching
## التخزين المؤقت للموجهات
يدعم OpenClaw ميزة Prompt caching الخاصة بـ Anthropic عند استخدام مصادقة مفتاح API.
يدعم OpenClaw ميزة التخزين المؤقت للموجهات الخاصة بـ Anthropic لمصادقة مفتاح API.
| القيمة | مدة cache | الوصف |
| ------------------- | -------------- | -------------------------------------- |
| `"short"` (الافتراضي) | 5 دقائق | تُطبَّق تلقائيًا عند استخدام مصادقة مفتاح API |
| `"long"` | ساعة واحدة | cache ممتدة |
| `"none"` | من دون cache | تعطيل Prompt caching |
| القيمة | مدة التخزين المؤقت | الوصف |
| ------------------- | ------------------ | ------------------------------------------ |
| `"short"` (افتراضي) | 5 دقائق | يُطبّق تلقائيًا لمصادقة مفتاح API |
| `"long"` | ساعة واحدة | تخزين مؤقت ممتد |
| `"none"` | بلا تخزين مؤقت | تعطيل التخزين المؤقت للموجهات |
```json5
{
@ -164,8 +164,8 @@ x-i18n:
```
<AccordionGroup>
<Accordion title="تجاوزات cache لكل وكيل">
استخدم معاملات النموذج على أنها خط الأساس، ثم تجاوز وكلاء محددين عبر `agents.list[].params`:
<Accordion title="تجاوزات التخزين المؤقت لكل agent">
استخدم معاملات مستوى النموذج كخط أساس، ثم تجاوز agents محددين عبر `agents.list[].params`:
```json5
{
@ -186,29 +186,29 @@ x-i18n:
}
```
ترتيب دمج الإعدادات:
ترتيب دمج التكوين:
1. `agents.defaults.models["provider/model"].params`
2. `agents.list[].params` (مطابقة بحسب `id`، مع التجاوز حسب المفتاح)
2. `agents.list[].params` (مطابقة حسب `id`، مع التجاوز حسب المفتاح)
يتيح هذا لوكيل واحد الاحتفاظ بـ cache طويلة العمر، بينما يعطّل وكيل آخر على النموذج نفسه التخزين المؤقت لحركة المرور المتقطعة/منخفضة إعادة الاستخدام.
يتيح هذا لوكيل واحد الاحتفاظ بتخزين مؤقت طويل العمر بينما يعطّل وكيل آخر على النموذج نفسه التخزين المؤقت لحركة المرور المتدفقة/منخفضة إعادة الاستخدام.
</Accordion>
<Accordion title="ملاحظات Claude على Bedrock">
- تقبل نماذج Anthropic Claude على Bedrock (`amazon-bedrock/*anthropic.claude*`) تمرير `cacheRetention` عند ضبطها.
- تُفرض القيمة `cacheRetention: "none"` وقت التشغيل على نماذج Bedrock غير التابعة لـ Anthropic.
- كما أن الافتراضات الذكية لمفتاح API تضبط `cacheRetention: "short"` تلقائيًا لمراجع Claude-on-Bedrock عند عدم وجود قيمة صريحة.
- تقبل نماذج Anthropic Claude على Bedrock (`amazon-bedrock/*anthropic.claude*`) تمرير `cacheRetention` عند ضبطه.
- تُفرض قيمة `cacheRetention: "none"` وقت التشغيل على نماذج Bedrock غير التابعة لـ Anthropic.
- كما تضبط الإعدادات الذكية الافتراضية لمفتاح API القيمة `cacheRetention: "short"` لمراجع Claude-on-Bedrock عندما لا تكون هناك قيمة صريحة مضبوطة.
</Accordion>
</AccordionGroup>
## إعدادات متقدمة
## التكوين المتقدم
<AccordionGroup>
<Accordion title="الوضع السريع">
يدعم مفتاح `/fast` المشترك في OpenClaw حركة Anthropic المباشرة (مفتاح API وOAuth إلى `api.anthropic.com`).
يدعم مفتاح التبديل المشترك `/fast` في OpenClaw حركة Anthropic المباشرة (مفتاح API وOAuth إلى `api.anthropic.com`).
| الأمر | يُطابِق |
| الأمر | يقابل |
|---------|---------|
| `/fast on` | `service_tier: "auto"` |
| `/fast off` | `service_tier: "standard_only"` |
@ -228,30 +228,30 @@ x-i18n:
```
<Note>
- لا يُحقن إلا للطلبات المباشرة إلى `api.anthropic.com`. أما مسارات proxy فتترك `service_tier` من دون تعديل.
- تتجاوز معاملات `serviceTier` أو `service_tier` الصريحة إعداد `/fast` عندما يكون كلاهما مضبوطًا.
- في الحسابات التي لا تملك سعة Priority Tier، قد تُحل `service_tier: "auto"` إلى `standard`.
- يُحقن فقط لطلبات `api.anthropic.com` المباشرة. وتترك مسارات proxy قيمة `service_tier` دون تعديل.
- تتجاوز معاملات `serviceTier` أو `service_tier` الصريحة `/fast` عند ضبط الاثنين معًا.
- في الحسابات التي لا تتوفر فيها سعة Priority Tier، قد تُحل `service_tier: "auto"` إلى `standard`.
</Note>
</Accordion>
<Accordion title="فهم الوسائط (الصور وPDF)">
يسجل Plugin Anthropic المضمّن فهم الصور وPDF. ويقوم OpenClaw
بحل قدرات الوسائط تلقائيًا من مصادقة Anthropic المضبوطة — من دون
حاجة إلى إعدادات إضافية.
يسجّل Plugin Anthropic المضمّن فهم الصور وملفات PDF. ويقوم OpenClaw
بحل قدرات الوسائط تلقائيًا من مصادقة Anthropic المضبوطة — ولا
حاجة إلى أي تكوين إضافي.
| الخاصية | القيمة |
| -------------- | -------------------- |
| النموذج الافتراضي | `claude-opus-4-6` |
| الإدخال المدعوم | الصور، ومستندات PDF |
| الإدخال المدعوم | الصور، مستندات PDF |
عند إرفاق صورة أو PDF بمحادثة، يقوم OpenClaw تلقائيًا
بتوجيهها عبر مزوّد فهم الوسائط الخاص بـ Anthropic.
عند إرفاق صورة أو ملف PDF بمحادثة، يقوم OpenClaw تلقائيًا
بتوجيهه عبر موفر فهم الوسائط الخاص بـ Anthropic.
</Accordion>
<Accordion title="نافذة سياق 1M (بيتا)">
نافذة سياق 1M من Anthropic محكومة ببوابة beta. فعّلها لكل نموذج:
<Accordion title="نافذة سياق 1M (تجريبية)">
بوابة الإصدار التجريبي الخاصة بـ Anthropic لنافذة سياق 1M. فعّلها لكل نموذج:
```json5
{
@ -270,36 +270,34 @@ x-i18n:
يربط OpenClaw هذا إلى `anthropic-beta: context-1m-2025-08-07` في الطلبات.
<Warning>
يتطلب هذا وصول السياق الطويل على بيانات اعتماد Anthropic لديك. وتُرفض مصادقة الرموز القديمة (`sk-ant-oat-*`) لطلبات سياق 1M — يسجل OpenClaw تحذيرًا ويعود إلى نافذة السياق القياسية.
يتطلب ذلك وصول السياق الطويل في بيانات اعتماد Anthropic الخاصة بك. يتم رفض مصادقة الرموز القديمة (`sk-ant-oat-*`) لطلبات سياق 1M — ويسجل OpenClaw تحذيرًا ويعود إلى نافذة السياق القياسية.
</Warning>
</Accordion>
<Accordion title="تطبيع سياق 1M في Claude Opus 4.7">
يجري تطبيع Claude Opus 4.7 (`anthropic/claude-opus-4.7`) ومتغيره `claude-cli` إلى نافذة سياق 1M في بيانات بيئة التشغيل الوصفية المحلولة وفي تقارير الحالة/السياق للوكلاء النشطين. ولا تحتاج إلى `params.context1m: true` في Opus 4.7؛ فهو لم يعد يرث fallback القديم البالغ 200k.
ويستخدم Compaction ومعالجة الفائض نافذة 1M تلقائيًا. أما نماذج Anthropic الأخرى فتبقي على حدودها المنشورة.
<Accordion title="سياق 1M لـ Claude Opus 4.7">
يملك `anthropic/claude-opus-4.7` ومتغير `claude-cli` الخاص به نافذة
سياق 1M افتراضيًا — ولا حاجة إلى `params.context1m: true`.
</Accordion>
</AccordionGroup>
## استكشاف الأخطاء وإصلاحها
<AccordionGroup>
<Accordion title="أخطاء 401 / الرمز أصبح غير صالح فجأة">
يمكن أن تنتهي صلاحية مصادقة رمز Anthropic أو تُلغى. بالنسبة إلى الإعدادات الجديدة، انتقل إلى مفتاح Anthropic API.
<Accordion title="أخطاء 401 / أصبح الرمز غير صالح فجأة">
قد تنتهي صلاحية مصادقة رموز Anthropic أو تُلغى. بالنسبة للإعدادات الجديدة، انتقل إلى مفتاح Anthropic API.
</Accordion>
<Accordion title='لم يتم العثور على مفتاح API للمزوّد "anthropic"'>
المصادقة **لكل وكيل**. لا ترث الوكلاء الجدد مفاتيح الوكيل الرئيسي. أعد تشغيل الإعداد الأولي لذلك الوكيل، أو اضبط مفتاح API على مضيف gateway، ثم تحقق باستخدام `openclaw models status`.
<Accordion title='لم يتم العثور على مفتاح API للموفر "anthropic"'>
تتم المصادقة **لكل agent**. لا ترث agents الجديدة مفاتيح agent الرئيسي. أعد تشغيل الإعداد الأولي لذلك agent، أو اضبط مفتاح API على مضيف gateway، ثم تحقق باستخدام `openclaw models status`.
</Accordion>
<Accordion title='لم يتم العثور على بيانات اعتماد لملف التعريف "anthropic:default"'>
شغّل `openclaw models status` لمعرفة ملف تعريف المصادقة النشط. أعد تشغيل الإعداد الأولي، أو اضبط مفتاح API لذلك المسار الخاص بملف التعريف.
شغّل `openclaw models status` لمعرفة ملف تعريف المصادقة النشط. أعد تشغيل الإعداد الأولي، أو اضبط مفتاح API لمسار ملف التعريف هذا.
</Accordion>
<Accordion title="لا يوجد ملف تعريف مصادقة متاح (الجميع في فترة تهدئة)">
تحقق من `openclaw models status --json` لمعرفة `auth.unusableProfiles`. وقد تكون فترات تهدئة حد المعدل في Anthropic محصورة بالنموذج، لذلك قد يظل نموذج Anthropic شقيق قابلًا للاستخدام. أضف ملف تعريف Anthropic آخر أو انتظر حتى تنتهي فترة التهدئة.
<Accordion title="لا يوجد ملف تعريف مصادقة متاح (الكل في فترة تهدئة)">
تحقق من `openclaw models status --json` لمعرفة `auth.unusableProfiles`. قد تكون فترات التهدئة الخاصة بحدود معدل Anthropic مرتبطة بالنموذج، لذلك قد يظل نموذج Anthropic شقيق قابلًا للاستخدام. أضف ملف تعريف Anthropic آخر أو انتظر انتهاء فترة التهدئة.
</Accordion>
</AccordionGroup>
@ -311,13 +309,13 @@ x-i18n:
<CardGroup cols={2}>
<Card title="اختيار النموذج" href="/ar/concepts/model-providers" icon="layers">
اختيار المزوّدين، ومراجع النماذج، وسلوك الانتقال الاحتياطي.
اختيار الموفرين ومراجع النماذج وسلوك تجاوز الفشل.
</Card>
<Card title="الواجهات الخلفية لـ CLI" href="/ar/gateway/cli-backends" icon="terminal">
إعداد الواجهة الخلفية Claude CLI وتفاصيل بيئة التشغيل.
<Card title="واجهات CLI الخلفية" href="/ar/gateway/cli-backends" icon="terminal">
إعداد الواجهة الخلفية لـ Claude CLI وتفاصيل وقت التشغيل.
</Card>
<Card title="Prompt caching" href="/ar/reference/prompt-caching" icon="database">
كيف يعمل Prompt caching عبر المزوّدين.
<Card title="التخزين المؤقت للموجهات" href="/ar/reference/prompt-caching" icon="database">
كيف يعمل التخزين المؤقت للموجهات عبر الموفّرين.
</Card>
<Card title="OAuth والمصادقة" href="/ar/gateway/authentication" icon="key">
تفاصيل المصادقة وقواعد إعادة استخدام بيانات الاعتماد.

110
docs/ar/providers/bedrock-mantle.md
View File

@ -2,30 +2,30 @@
read_when:
- تريد استخدام نماذج OSS المستضافة على Bedrock Mantle مع OpenClaw
- تحتاج إلى نقطة نهاية Mantle المتوافقة مع OpenAI لـ GPT-OSS أو Qwen أو Kimi أو GLM
summary: استخدام نماذج Amazon Bedrock Mantle (المتوافقة مع OpenAI) مع OpenClaw
summary: استخدم نماذج Amazon Bedrock Mantle المتوافقة مع OpenAI مع OpenClaw
title: Amazon Bedrock Mantle
x-i18n:
generated_at: "2026-04-23T07:30:52Z"
generated_at: "2026-04-23T14:01:40Z"
model: gpt-5.4
provider: openai
source_hash: b7b3ba0e0a6a175ca1159c0c8ac9cf13a43dfb59b7bb106089c635876c349c61
source_hash: a20e0abcd140b3c7115a9b0bbdf924e15962e0452ded676df252c753610e03ed
source_path: providers/bedrock-mantle.md
workflow: 15
---
# Amazon Bedrock Mantle
يتضمن OpenClaw مزود **Amazon Bedrock Mantle** مضمّنًا يتصل
يتضمن OpenClaw مزود **Amazon Bedrock Mantle** مدمجًا يتصل
بنقطة نهاية Mantle المتوافقة مع OpenAI. تستضيف Mantle نماذج مفتوحة المصدر
ونماذج من جهات خارجية (مثل GPT-OSS وQwen وKimi وGLM وما شابهها) عبر
سطح قياسي من نوع `/v1/chat/completions` مدعوم ببنية Bedrock التحتية.
ونماذج تابعة لجهات خارجية (مثل GPT-OSS وQwen وKimi وGLM وما شابه) عبر
واجهة ` /v1/chat/completions ` قياسية مدعومة ببنية Bedrock التحتية.
| الخاصية | القيمة |
| -------------- | ------------------------------------------------------------------------------------------- |
| معرّف المزوّد | `amazon-bedrock-mantle` |
| API | `openai-completions` (متوافق مع OpenAI) أو `anthropic-messages` (مسار Anthropic Messages) |
| المصادقة | `AWS_BEARER_TOKEN_BEDROCK` صريح أو توليد bearer token من سلسلة بيانات اعتماد IAM |
| المنطقة الافتراضية | `us-east-1` (يمكن تجاوزها باستخدام `AWS_REGION` أو `AWS_DEFAULT_REGION`) |
| الخاصية | القيمة |
| -------------- | ---------------------------------------------------------------------------------------------- |
| معرّف المزود | `amazon-bedrock-mantle` |
| API | `openai-completions` (متوافق مع OpenAI) أو `anthropic-messages` (مسار Anthropic Messages) |
| المصادقة | `AWS_BEARER_TOKEN_BEDROCK` صريح أو إنشاء bearer token عبر سلسلة بيانات اعتماد IAM |
| المنطقة الافتراضية | `us-east-1` (يمكن تجاوزها باستخدام `AWS_REGION` أو `AWS_DEFAULT_REGION`) |
## البدء
@ -33,21 +33,21 @@ x-i18n:
<Tabs>
<Tab title="Explicit bearer token">
**الأفضل لـ:** البيئات التي لديك فيها بالفعل Mantle bearer token.
**الأفضل لـ:** البيئات التي لديك فيها بالفعل bearer token لـ Mantle.
<Steps>
<Step title="Set the bearer token on the gateway host">
<Step title="تعيين bearer token على مضيف Gateway">
```bash
export AWS_BEARER_TOKEN_BEDROCK="..."
```
يمكنك اختياريًا ضبط منطقة (الافتراضي `us-east-1`):
ويمكنك اختياريًا تعيين منطقة (الافتراضية هي `us-east-1`):
```bash
export AWS_REGION="us-west-2"
```
</Step>
<Step title="Verify models are discovered">
<Step title="التحقق من اكتشاف النماذج">
```bash
openclaw models list
```
@ -60,10 +60,10 @@ x-i18n:
</Tab>
<Tab title="IAM credentials">
**الأفضل لـ:** استخدام بيانات اعتماد متوافقة مع AWS SDK (التهيئة المشتركة، وSSO، وweb identity، أو أدوار المثيل أو المهمة).
**الأفضل لـ:** استخدام بيانات اعتماد متوافقة مع AWS SDK (إعدادات مشتركة، أو SSO، أو web identity، أو أدوار المثيل أو المهمة).
<Steps>
<Step title="Configure AWS credentials on the gateway host">
<Step title="إعداد بيانات اعتماد AWS على مضيف Gateway">
أي مصدر مصادقة متوافق مع AWS SDK يعمل:
```bash
@ -71,47 +71,47 @@ x-i18n:
export AWS_REGION="us-west-2"
```
</Step>
<Step title="Verify models are discovered">
<Step title="التحقق من اكتشاف النماذج">
```bash
openclaw models list
```
يقوم OpenClaw بتوليد Mantle bearer token من سلسلة بيانات الاعتماد تلقائيًا.
ينشئ OpenClaw bearer token لـ Mantle من سلسلة بيانات الاعتماد تلقائيًا.
</Step>
</Steps>
<Tip>
عندما لا تكون `AWS_BEARER_TOKEN_BEDROCK` مضبوطة، يقوم OpenClaw بإصدار bearer token نيابةً عنك من سلسلة بيانات اعتماد AWS الافتراضية، بما في ذلك ملفات تعريف بيانات الاعتماد/التهيئة المشتركة، وSSO، وweb identity، وأدوار المثيل أو المهمة.
عندما لا يكون `AWS_BEARER_TOKEN_BEDROCK` مضبوطًا، ينشئ OpenClaw bearer token لك من سلسلة بيانات الاعتماد الافتراضية في AWS، بما في ذلك ملفات بيانات الاعتماد/الإعدادات المشتركة، وSSO، وweb identity، وأدوار المثيل أو المهمة.
</Tip>
</Tab>
</Tabs>
## الاكتشاف التلقائي للنماذج
## الاكتشاف التلقائي للنموذج
عندما تكون `AWS_BEARER_TOKEN_BEDROCK` مضبوطة، يستخدمها OpenClaw مباشرة. وإلا،
يحاول OpenClaw توليد Mantle bearer token من سلسلة بيانات اعتماد AWS
الافتراضية. ثم يكتشف نماذج Mantle المتاحة عبر الاستعلام من
عندما يكون `AWS_BEARER_TOKEN_BEDROCK` مضبوطًا، يستخدمه OpenClaw مباشرةً. وإلا،
يحاول OpenClaw إنشاء bearer token لـ Mantle من سلسلة بيانات الاعتماد
الافتراضية في AWS. ثم يكتشف نماذج Mantle المتاحة عبر الاستعلام عن
نقطة النهاية `/v1/models` الخاصة بالمنطقة.
| السلوك | التفاصيل |
| ----------------- | ------------------------- |
| cache الاكتشاف | يتم تخزين النتائج مؤقتًا لمدة ساعة واحدة |
| تحديث IAM token | كل ساعة |
| السلوك | التفاصيل |
| -------------------- | ------------------------ |
| ذاكرة التخزين المؤقت للاكتشاف | تُخزَّن النتائج مؤقتًا لمدة ساعة |
| تحديث رمز IAM | كل ساعة |
<Note>
إن bearer token هي نفسها `AWS_BEARER_TOKEN_BEDROCK` المستخدمة بواسطة المزود القياسي [Amazon Bedrock](/ar/providers/bedrock).
bearer token هو نفسه `AWS_BEARER_TOKEN_BEDROCK` المستخدم من قبل مزود [Amazon Bedrock](/ar/providers/bedrock) القياسي.
</Note>
### المناطق المدعومة
`us-east-1` و`us-east-2` و`us-west-2` و`ap-northeast-1`،
و`ap-south-1` و`ap-southeast-3` و`eu-central-1` و`eu-west-1` و`eu-west-2`،
و`eu-south-1` و`eu-north-1` و`sa-east-1`.
`ap-south-1` و`ap-southeast-3` و`eu-central-1` و`eu-west-1` و`eu-west-2`،
`eu-south-1` و`eu-north-1` و`sa-east-1`.
## التهيئة اليدوية
## الإعداد اليدوي
إذا كنت تفضل تهيئة صريحة بدلًا من الاكتشاف التلقائي:
إذا كنت تفضل الإعداد الصريح بدلًا من الاكتشاف التلقائي:
```json5
{
@ -142,22 +142,22 @@ x-i18n:
## ملاحظات متقدمة
<AccordionGroup>
<Accordion title="Reasoning support">
يُستدل على دعم reasoning من معرّفات النماذج التي تحتوي على أنماط مثل
`thinking` أو `reasoner` أو `gpt-oss-120b`. ويضبط OpenClaw القيمة `reasoning: true`
<Accordion title="دعم الاستدلال">
يُستنتج دعم الاستدلال من معرّفات النماذج التي تحتوي على أنماط مثل
`thinking` أو `reasoner` أو `gpt-oss-120b`. ويضبط OpenClaw الخاصية `reasoning: true`
تلقائيًا للنماذج المطابقة أثناء الاكتشاف.
</Accordion>
<Accordion title="Endpoint unavailability">
<Accordion title="عدم توفر نقطة النهاية">
إذا كانت نقطة نهاية Mantle غير متاحة أو لم تُرجع أي نماذج، فسيتم
تخطي المزود بصمت. ولا يصدر OpenClaw خطأ؛ وتستمر المزوّدات المهيأة
الأخرى في العمل بشكل طبيعي.
تخطي المزود بصمت. ولا يُصدر OpenClaw خطأ؛ وتستمر المزودات
الأخرى المُعدّة في العمل بشكل طبيعي.
</Accordion>
<Accordion title="Claude Opus 4.7 via the Anthropic Messages route">
تكشف Mantle أيضًا عن مسار Anthropic Messages ينقل نماذج Claude عبر مسار البث نفسه الموثّق باستخدام bearer token. ويمكن استدعاء Claude Opus 4.7 (`amazon-bedrock-mantle/claude-opus-4.7`) عبر هذا المسار باستخدام البث المملوك للمزوّد، لذلك لا تُعامل AWS bearer tokens على أنها مفاتيح Anthropic API.
<Accordion title="Claude Opus 4.7 عبر مسار Anthropic Messages">
يعرّض Mantle أيضًا مسار Anthropic Messages يحمل نماذج Claude عبر مسار البث نفسه الموثّق باستخدام bearer. ويمكن استدعاء Claude Opus 4.7 (`amazon-bedrock-mantle/claude-opus-4.7`) عبر هذا المسار مع بث مملوك للمزوّد، لذلك لا تُعامل bearer tokens الخاصة بـ AWS كما لو كانت مفاتيح Anthropic API.
عندما تثبّت نموذج Anthropic Messages على مزود Mantle، يستخدم OpenClaw سطح API من نوع `anthropic-messages` بدلًا من `openai-completions` لذلك النموذج. وتظل المصادقة قادمة من `AWS_BEARER_TOKEN_BEDROCK` (أو من IAM bearer token المُولَّد).
عندما تثبّت نموذج Anthropic Messages على مزود Mantle، يستخدم OpenClaw واجهة API `anthropic-messages` بدلًا من `openai-completions` لهذا النموذج. ولا تزال المصادقة تأتي من `AWS_BEARER_TOKEN_BEDROCK` (أو bearer token الخاص بـ IAM الذي تم إنشاؤه).
```json5
{
@ -181,18 +181,16 @@ x-i18n:
}
```
تستخدم بيانات context-window الوصفية لنماذج Mantle المكتشفة الحدود المنشورة المعروفة عند توفرها، وتعود بشكل متحفظ للنماذج غير المدرجة، بحيث يتصرف كل من Compaction ومعالجة overflow بشكل صحيح مع الإدخالات الأحدث من دون المبالغة في النماذج غير المعروفة.
</Accordion>
<Accordion title="Relationship to Amazon Bedrock provider">
<Accordion title="العلاقة بمزود Amazon Bedrock">
يُعد Bedrock Mantle مزودًا منفصلًا عن مزود
[Amazon Bedrock](/ar/providers/bedrock) القياسي. يستخدم Mantle سطحًا
متوافقًا مع OpenAI من نوع `/v1`، بينما يستخدم مزود Bedrock القياسي
Bedrock API الأصلية.
[Amazon Bedrock](/ar/providers/bedrock) القياسي. يستخدم Mantle
واجهة `/v1` متوافقة مع OpenAI، بينما يستخدم مزود Bedrock القياسي
Bedrock API الأصلي.
يشترك كلا المزودين في بيانات الاعتماد نفسها `AWS_BEARER_TOKEN_BEDROCK` عند
توفرها.
يشترك كلا المزودين في بيانات الاعتماد نفسها `AWS_BEARER_TOKEN_BEDROCK`
عند وجودها.
</Accordion>
</AccordionGroup>
@ -201,15 +199,15 @@ x-i18n:
<CardGroup cols={2}>
<Card title="Amazon Bedrock" href="/ar/providers/bedrock" icon="cloud">
مزود Bedrock الأصلي لنماذج Anthropic Claude وTitan ونماذج أخرى.
مزود Bedrock أصلي لـ Anthropic Claude وTitan ونماذج أخرى.
</Card>
<Card title="Model selection" href="/ar/concepts/model-providers" icon="layers">
اختيار المزوّدات، ومراجع النماذج، وسلوك failover.
<Card title="اختيار النموذج" href="/ar/concepts/model-providers" icon="layers">
اختيار المزودات ومراجع النماذج وسلوك التبديل الاحتياطي.
</Card>
<Card title="OAuth and auth" href="/ar/gateway/authentication" icon="key">
<Card title="OAuth والمصادقة" href="/ar/gateway/authentication" icon="key">
تفاصيل المصادقة وقواعد إعادة استخدام بيانات الاعتماد.
</Card>
<Card title="Troubleshooting" href="/ar/help/troubleshooting" icon="wrench">
<Card title="استكشاف الأخطاء وإصلاحها" href="/ar/help/troubleshooting" icon="wrench">
المشكلات الشائعة وكيفية حلها.
</Card>
</CardGroup>

66
docs/ar/providers/lmstudio.md
View File

@ -1,33 +1,33 @@
---
read_when:
- تريد تشغيل OpenClaw مع نماذج مفتوحة المصدر عبر LM Studio
- تريد تشغيل OpenClaw باستخدام نماذج مفتوحة المصدر عبر LM Studio
- تريد إعداد LM Studio وتهيئته
summary: شغّل OpenClaw مع LM Studio
summary: شغّل OpenClaw باستخدام LM Studio
title: LM Studio
x-i18n:
generated_at: "2026-04-23T07:31:22Z"
generated_at: "2026-04-23T14:01:44Z"
model: gpt-5.4
provider: openai
source_hash: 733527e95041da04562c0ee5d9486750d8355a255624a6d5735954de34429a5c
source_hash: 062b26cf10631e74f4e1917ea9011133eb4433f5fb7ee85748d00080a6ca212d
source_path: providers/lmstudio.md
workflow: 15
---
# LM Studio
LM Studio هو تطبيق سهل الاستخدام وقوي لتشغيل النماذج ذات الأوزان المفتوحة على عتادك الخاص. ويتيح لك تشغيل نماذج llama.cpp ‏(GGUF) أو MLX ‏(على Apple Silicon). ويتوفر ضمن حزمة GUI أو كخادم بدون واجهة (`llmster`). وللاطلاع على وثائق المنتج والإعداد، راجع [lmstudio.ai](https://lmstudio.ai/).
يُعد LM Studio تطبيقًا سهل الاستخدام لكنه قوي لتشغيل النماذج مفتوحة الأوزان على عتادك الخاص. يتيح لك تشغيل نماذج llama.cpp ‏(GGUF) أو MLX ‏(Apple Silicon). ويتوفر كحزمة GUI أو daemon بدون واجهة (`llmster`). للاطلاع على وثائق المنتج والإعداد، راجع [lmstudio.ai](https://lmstudio.ai/).
## البدء السريع
1. ثبّت LM Studio (سطح المكتب) أو `llmster` (بدون واجهة)، ثم ابدأ تشغيل الخادم المحلي:
1. ثبّت LM Studio ‏(سطح المكتب) أو `llmster` ‏(بدون واجهة)، ثم ابدأ الخادم المحلي:
```bash
curl -fsSL https://lmstudio.ai/install.sh | bash
```
2. ابدأ تشغيل الخادم
2. ابدأ الخادم
تأكد من أنك إما بدأت تطبيق سطح المكتب أو شغّلت الخادم باستخدام الأمر التالي:
تأكد من أنك إما تشغّل تطبيق سطح المكتب أو تشغّل daemon باستخدام الأمر التالي:
```bash
lms daemon up
@ -37,21 +37,21 @@ lms daemon up
lms server start --port 1234
```
إذا كنت تستخدم التطبيق، فتأكد من تفعيل JIT للحصول على تجربة سلسة. تعرّف أكثر في [دليل LM Studio حول JIT وTTL](https://lmstudio.ai/docs/developer/core/ttl-and-auto-evict).
إذا كنت تستخدم التطبيق، فتأكد من تفعيل JIT للحصول على تجربة سلسة. تعرّف على المزيد في [دليل JIT وTTL في LM Studio](https://lmstudio.ai/docs/developer/core/ttl-and-auto-evict).
3. يتطلب OpenClaw قيمة token لـ LM Studio. اضبط `LM_API_TOKEN`:
3. يتطلب OpenClaw قيمة token خاصة بـ LM Studio. اضبط `LM_API_TOKEN`:
```bash
export LM_API_TOKEN="your-lm-studio-api-token"
```
إذا كانت مصادقة LM Studio معطلة، فاستخدم أي قيمة token غير فارغة:
إذا كانت المصادقة في LM Studio معطلة، فاستخدم أي قيمة token غير فارغة:
```bash
export LM_API_TOKEN="placeholder-key"
```
للحصول على تفاصيل إعداد مصادقة LM Studio، راجع [مصادقة LM Studio](https://lmstudio.ai/docs/developer/core/authentication).
للحصول على تفاصيل إعداد المصادقة في LM Studio، راجع [مصادقة LM Studio](https://lmstudio.ai/docs/developer/core/authentication).
4. شغّل الإعداد الأولي واختر `LM Studio`:
@ -59,7 +59,7 @@ export LM_API_TOKEN="placeholder-key"
openclaw onboard
```
5. في الإعداد الأولي، استخدم مطالبة `Default model` لاختيار نموذج LM Studio الخاص بك.
5. أثناء الإعداد الأولي، استخدم مطالبة `Default model` لاختيار نموذج LM Studio الخاص بك.
يمكنك أيضًا ضبطه أو تغييره لاحقًا:
@ -67,13 +67,13 @@ openclaw onboard
openclaw models set lmstudio/qwen/qwen3.5-9b
```
تتبع مفاتيح نماذج LM Studio تنسيق `author/model-name` (مثل `qwen/qwen3.5-9b`). وتسبق مراجع
النماذج في OpenClaw اسم المزوّد: `lmstudio/qwen/qwen3.5-9b`. ويمكنك العثور على المفتاح الدقيق
للنموذج عبر تشغيل `curl http://localhost:1234/api/v1/models` والنظر إلى الحقل `key`.
تتبع مفاتيح النماذج في LM Studio تنسيق `author/model-name` ‏(مثل `qwen/qwen3.5-9b`). وتضيف مراجع النماذج في OpenClaw
اسم المزوّد في البداية: `lmstudio/qwen/qwen3.5-9b`. ويمكنك العثور على المفتاح الدقيق
لنموذج ما عبر تشغيل `curl http://localhost:1234/api/v1/models` والنظر إلى الحقل `key`.
## الإعداد الأولي غير التفاعلي
استخدم الإعداد الأولي غير التفاعلي عندما تريد برمجة الإعداد نصيًا (CI، أو التزويد، أو التمهيد البعيد):
استخدم الإعداد الأولي غير التفاعلي عندما تريد أتمتة الإعداد (CI، أو التهيئة، أو bootstrap عن بُعد):
```bash
openclaw onboard \
@ -94,26 +94,28 @@ openclaw onboard \
--custom-model-id qwen/qwen3.5-9b
```
تأخذ `--custom-model-id` مفتاح النموذج كما يعيده LM Studio (مثل `qwen/qwen3.5-9b`) من دون
يأخذ `--custom-model-id` مفتاح النموذج كما يعيده LM Studio ‏(مثل `qwen/qwen3.5-9b`) من دون
بادئة المزوّد `lmstudio/`.
يتطلب الإعداد الأولي غير التفاعلي `--lmstudio-api-key` (أو `LM_API_TOKEN` في env).
وبالنسبة إلى خوادم LM Studio غير المصادق عليها، تعمل أي قيمة token غير فارغة.
وبالنسبة إلى خوادم LM Studio غير الموثقة، فإن أي قيمة token غير فارغة تعمل.
يبقى `--custom-api-key` مدعومًا للتوافق، لكن `--lmstudio-api-key` هو المفضل لـ LM Studio.
ما يزال `--custom-api-key` مدعومًا للتوافق، لكن `--lmstudio-api-key` هو المفضل مع LM Studio.
يكتب هذا `models.providers.lmstudio`، ويضبط النموذج الافتراضي على
`lmstudio/<custom-model-id>`, ويكتب ملف تعريف المصادقة `lmstudio:default`.
يؤدي هذا إلى كتابة `models.providers.lmstudio`، وضبط النموذج الافتراضي إلى
`lmstudio/<custom-model-id>`، وكتابة ملف تعريف auth ‏`lmstudio:default`.
يمكن أن يطلب الإعداد التفاعلي طول سياق تحميل مفضّلًا اختياريًا ويطبقه على نماذج LM Studio المكتشفة التي يحفظها في الإعدادات.
يمكن للإعداد التفاعلي أن يطلب طول preferred load context اختياريًا ويطبقه على نماذج LM Studio المكتشفة التي يحفظها في config.
## الإعدادات
### توافق استخدام البث المتدفق
### توافق استخدام البث
يضع OpenClaw علامة على LM Studio على أنه متوافق مع استخدام البث المتدفق، لذلك لم يعد حساب الرموز يتدهور إلى إجماليات مجهولة أو قديمة في الإكمالات المتدفقة. كما يستعيد OpenClaw أيضًا أعداد الرموز من بيانات `timings.prompt_n` / `timings.predicted_n` الوصفية على نمط llama.cpp عندما لا يرسل LM Studio كائن `usage` بشكل OpenAI.
يتوافق LM Studio مع streaming-usage. وعندما لا يصدر كائن `usage`
بصيغة OpenAI، يستعيد OpenClaw أعداد tokens من بيانات
`timings.prompt_n` / `timings.predicted_n` الوصفية بصيغة llama.cpp بدلًا من ذلك.
واجهات خلفية محلية أخرى متوافقة مع OpenAI يشملها السلوك نفسه:
ينطبق السلوك نفسه على backends المحلية المتوافقة مع OpenAI التالية:
- vLLM
- SGLang
@ -154,14 +156,14 @@ openclaw onboard \
### لم يتم اكتشاف LM Studio
تأكد من أن LM Studio يعمل وأنك ضبطت `LM_API_TOKEN` (وبالنسبة إلى الخوادم غير المصادق عليها، تعمل أي قيمة token غير فارغة):
تأكد من أن LM Studio قيد التشغيل وأنك ضبطت `LM_API_TOKEN` (وبالنسبة إلى الخوادم غير الموثقة، فإن أي قيمة token غير فارغة تعمل):
```bash
# ابدأ عبر تطبيق سطح المكتب، أو بدون واجهة:
lms server start --port 1234
```
تحقق من أن API قابلة للوصول:
تحقق من أن API متاحة:
```bash
curl http://localhost:1234/api/v1/models
@ -172,9 +174,9 @@ curl http://localhost:1234/api/v1/models
إذا أبلغ الإعداد عن HTTP 401، فتحقق من مفتاح API الخاص بك:
- تأكد من أن `LM_API_TOKEN` يطابق المفتاح المضبوط في LM Studio.
- للحصول على تفاصيل إعداد مصادقة LM Studio، راجع [مصادقة LM Studio](https://lmstudio.ai/docs/developer/core/authentication).
- إذا كان الخادم لديك لا يتطلب مصادقة، فاستخدم أي قيمة token غير فارغة لـ `LM_API_TOKEN`.
- للحصول على تفاصيل إعداد المصادقة في LM Studio، راجع [مصادقة LM Studio](https://lmstudio.ai/docs/developer/core/authentication).
- إذا كان خادمك لا يتطلب مصادقة، فاستخدم أي قيمة token غير فارغة لـ `LM_API_TOKEN`.
### تحميل النموذج عند الطلب
### التحميل الفوري للنموذج
يدعم LM Studio تحميل النموذج عند الطلب (JIT)، حيث تُحمَّل النماذج عند أول طلب. تأكد من تفعيل ذلك لتجنب أخطاء 'Model not loaded'.
يدعم LM Studio التحميل الفوري للنموذج (JIT)، حيث تُحمَّل النماذج عند أول طلب. تأكد من تفعيل هذا لتجنب أخطاء "Model not loaded".

157
docs/ar/providers/moonshot.md
View File

@ -1,52 +1,52 @@
---
read_when:
- تريد إعداد Moonshot K2 (Moonshot Open Platform) مقابل Kimi Coding
- تريد إعداد Moonshot K2 ‏(Moonshot Open Platform) مقابل Kimi Coding
- تحتاج إلى فهم نقاط النهاية والمفاتيح ومراجع النماذج المنفصلة
- تريد إعدادات جاهزة للنسخ واللصق لأي من المزوّدين
summary: ضبط Moonshot K2 مقابل Kimi Coding (مزوّدان منفصلان + مفاتيح منفصلة)
summary: تهيئة Moonshot K2 مقابل Kimi Coding (مزودون منفصلون + مفاتيح منفصلة)
title: Moonshot AI
x-i18n:
generated_at: "2026-04-23T07:31:42Z"
generated_at: "2026-04-23T14:02:08Z"
model: gpt-5.4
provider: openai
source_hash: d9a726df279bfc0351b8ab224e682b5c1e6e360440659e33e8568a94c351df51
source_hash: e143632de7aff050f32917e379e21ace5f4a5f9857618ef720f885f2f298ca72
source_path: providers/moonshot.md
workflow: 15
---
# Moonshot AI (Kimi)
يوفر Moonshot واجهة Kimi API مع نقاط نهاية متوافقة مع OpenAI. اضبط
توفر Moonshot واجهة Kimi API مع نقاط نهاية متوافقة مع OpenAI. اضبط
المزوّد وحدد النموذج الافتراضي إلى `moonshot/kimi-k2.6`، أو استخدم
Kimi Coding مع `kimi/kimi-code`.
<Warning>
Moonshot وKimi Coding هما **مزوّدان منفصلان**. المفاتيح غير قابلة للتبادل، ونقاط النهاية مختلفة، ومراجع النماذج مختلفة (`moonshot/...` مقابل `kimi/...`).
Moonshot وKimi Coding هما **مزودان منفصلان**. المفاتيح غير قابلة للتبادل، ونقاط النهاية تختلف، ومراجع النماذج تختلف (`moonshot/...` مقابل `kimi/...`).
</Warning>
## فهرس النماذج المضمّن
## كتالوج النماذج المضمّن
[//]: # "moonshot-kimi-k2-ids:start"
| مرجع النموذج | الاسم | الاستدلال | الإدخال | السياق | الحد الأقصى للمخرجات |
| -------------------------------- | ---------------------- | --------- | ------------ | ------ | -------------------- |
| `moonshot/kimi-k2.6` | Kimi K2.6 | لا | نص، صورة | 262,144 | 262,144 |
| `moonshot/kimi-k2.5` | Kimi K2.5 | لا | نص، صورة | 262,144 | 262,144 |
| `moonshot/kimi-k2-thinking` | Kimi K2 Thinking | نعم | نص | 262,144 | 262,144 |
| `moonshot/kimi-k2-thinking-turbo`| Kimi K2 Thinking Turbo | نعم | نص | 262,144 | 262,144 |
| `moonshot/kimi-k2-turbo` | Kimi K2 Turbo | لا | نص | 256,000 | 16,384 |
| مرجع النموذج | الاسم | Reasoning | الإدخال | السياق | الحد الأقصى للإخراج |
| --------------------------------- | ---------------------- | --------- | ----------- | ------- | ---------- |
| `moonshot/kimi-k2.6` | Kimi K2.6 | لا | text, image | 262,144 | 262,144 |
| `moonshot/kimi-k2.5` | Kimi K2.5 | لا | text, image | 262,144 | 262,144 |
| `moonshot/kimi-k2-thinking` | Kimi K2 Thinking | نعم | text | 262,144 | 262,144 |
| `moonshot/kimi-k2-thinking-turbo` | Kimi K2 Thinking Turbo | نعم | text | 262,144 | 262,144 |
| `moonshot/kimi-k2-turbo` | Kimi K2 Turbo | لا | text | 256,000 | 16,384 |
[//]: # "moonshot-kimi-k2-ids:end"
تستخدم تقديرات التكلفة المضمّنة لنماذج K2 الحالية المستضافة على Moonshot
أسعار Moonshot المنشورة بنظام الدفع حسب الاستخدام: تبلغ تكلفة Kimi K2.6 مقدار $0.16/MTok عند إصابة cache hit،
و$0.95/MTok للإدخال، و$4.00/MTok للإخراج؛ بينما تبلغ تكلفة Kimi K2.5 مقدار $0.10/MTok عند إصابة cache hit،
و$0.60/MTok للإدخال، و$3.00/MTok للإخراج. أما إدخالات الفهرس القديمة الأخرى فتبقي
عناصر تكلفة صفرية نائبة ما لم تتجاوزها في config.
أسعار Moonshot المنشورة بنظام الدفع حسب الاستخدام: تبلغ تكلفة Kimi K2.6
‏$0.16/MTok لقراءة cache، و$0.95/MTok للإدخال، و$4.00/MTok للإخراج؛ وتبلغ تكلفة Kimi K2.5
‏$0.10/MTok لقراءة cache، و$0.60/MTok للإدخال، و$3.00/MTok للإخراج. أما إدخالات الكتالوج
القديمة الأخرى فتبقى بعناصر نائبة بتكلفة صفرية ما لم تتجاوزها في config.
## البدء
اختر المزوّد واتبع خطوات الإعداد.
اختر مزوّدك واتبع خطوات الإعداد.
<Tabs>
<Tab title="Moonshot API">
@ -54,17 +54,17 @@ Moonshot وKimi Coding هما **مزوّدان منفصلان**. المفاتي
<Steps>
<Step title="اختر منطقة نقطة النهاية">
| خيار المصادقة | نقطة النهاية | المنطقة |
| -------------------- | ----------------------------- | ------- |
| `moonshot-api-key` | `https://api.moonshot.ai/v1` | دولي |
| `moonshot-api-key-cn`| `https://api.moonshot.cn/v1` | الصين |
| خيار auth | نقطة النهاية | المنطقة |
| ---------------------- | ------------------------------ | ------------- |
| `moonshot-api-key` | `https://api.moonshot.ai/v1` | دولي |
| `moonshot-api-key-cn` | `https://api.moonshot.cn/v1` | الصين |
</Step>
<Step title="شغّل onboarding">
<Step title="شغّل الإعداد الأولي">
```bash
openclaw onboard --auth-choice moonshot-api-key
```
أو لنقطة النهاية الخاصة بالصين:
أو لنقطة نهاية الصين:
```bash
openclaw onboard --auth-choice moonshot-api-key-cn
@ -86,9 +86,9 @@ Moonshot وKimi Coding هما **مزوّدان منفصلان**. المفاتي
openclaw models list --provider moonshot
```
</Step>
<Step title="شغّل اختبارًا حيًا سريعًا">
<Step title="شغّل اختبار smoke حي">
استخدم دليل حالة معزولًا عندما تريد التحقق من الوصول إلى النموذج وتتبع
التكلفة من دون لمس جلساتك المعتادة:
التكلفة من دون لمس جلساتك العادية:
```bash
OPENCLAW_CONFIG_PATH=/tmp/openclaw-kimi/openclaw.json \
@ -101,9 +101,9 @@ Moonshot وKimi Coding هما **مزوّدان منفصلان**. المفاتي
```
يجب أن يبلّغ رد JSON عن `provider: "moonshot"` و
`model: "kimi-k2.6"`. ويخزن إدخال transcript الخاص بالمساعد
استخدام الرموز المطبّع بالإضافة إلى التكلفة المقدّرة تحت `usage.cost` عندما يعيد Moonshot
بيانات الاستخدام الوصفية.
`model: "kimi-k2.6"`. ويخزن إدخال سجل المساعد المطبّع
استخدام tokens بالإضافة إلى التكلفة التقديرية تحت `usage.cost` عندما تعيد Moonshot
بيانات usage الوصفية.
</Step>
</Steps>
@ -191,14 +191,14 @@ Moonshot وKimi Coding هما **مزوّدان منفصلان**. المفاتي
</Tab>
<Tab title="Kimi Coding">
**الأفضل لـ:** المهام التي تركّز على البرمجة عبر نقطة نهاية Kimi Coding.
**الأفضل لـ:** المهام التي تركز على البرمجة عبر نقطة نهاية Kimi Coding.
<Note>
يستخدم Kimi Coding مفتاح API مختلفًا وبادئة مزود مختلفة (`kimi/...`) عن Moonshot (`moonshot/...`). ولا يزال مرجع النموذج القديم `kimi/k2p5` مقبولًا كمعرّف توافق.
يستخدم Kimi Coding مفتاح API مختلفًا وبادئة مزوّد مختلفة (`kimi/...`) عن Moonshot ‏(`moonshot/...`). وما يزال مرجع النموذج القديم `kimi/k2p5` مقبولًا كمعرّف توافق.
</Note>
<Steps>
<Step title="شغّل onboarding">
<Step title="شغّل الإعداد الأولي">
```bash
openclaw onboard --auth-choice kimi-code-api-key
```
@ -240,32 +240,33 @@ Moonshot وKimi Coding هما **مزوّدان منفصلان**. المفاتي
</Tab>
</Tabs>
## البحث على الويب في Kimi
## بحث الويب في Kimi
يشحن OpenClaw أيضًا **Kimi** كمزوّد `web_search`، مدعومًا ببحث Moonshot على الويب.
يشحن OpenClaw أيضًا **Kimi** كمزوّد `web_search`، ومدعومًا ببحث الويب
في Moonshot.
<Steps>
<Step title="شغّل إعداد البحث على الويب التفاعلي">
<Step title="شغّل إعداد بحث الويب التفاعلي">
```bash
openclaw configure --section web
```
اختر **Kimi** في قسم البحث على الويب لتخزين
اختر **Kimi** في قسم بحث الويب لتخزين
`plugins.entries.moonshot.config.webSearch.*`.
</Step>
<Step title="اضبط منطقة البحث على الويب والنموذج">
يطالبك الإعداد التفاعلي بما يلي:
<Step title="اضبط منطقة بحث الويب والنموذج">
يطلب الإعداد التفاعلي ما يلي:
| الإعداد | الخيارات |
| ------------------- | -------- |
| منطقة API | `https://api.moonshot.ai/v1` (دولي) أو `https://api.moonshot.cn/v1` (الصين) |
| نموذج البحث على الويب | يكون الافتراضي `kimi-k2.6` |
| الإعداد | الخيارات |
| ------------------- | -------------------------------------------------------------------- |
| منطقة API | `https://api.moonshot.ai/v1` (دولي) أو `https://api.moonshot.cn/v1` (الصين) |
| نموذج بحث الويب | القيمة الافتراضية هي `kimi-k2.6` |
</Step>
</Steps>
توجد الإعدادات تحت `plugins.entries.moonshot.config.webSearch`:
يوجد config تحت `plugins.entries.moonshot.config.webSearch`:
```json5
{
@ -274,7 +275,7 @@ Moonshot وKimi Coding هما **مزوّدان منفصلان**. المفاتي
moonshot: {
config: {
webSearch: {
apiKey: "sk-...", // or use KIMI_API_KEY / MOONSHOT_API_KEY
apiKey: "sk-...", // أو استخدم KIMI_API_KEY / MOONSHOT_API_KEY
baseUrl: "https://api.moonshot.ai/v1",
model: "kimi-k2.6",
},
@ -295,8 +296,8 @@ Moonshot وKimi Coding هما **مزوّدان منفصلان**. المفاتي
## متقدم
<AccordionGroup>
<Accordion title="وضع التفكير الأصلي">
يدعم Moonshot Kimi وضع تفكير أصليًا ثنائيًا:
<Accordion title="وضع thinking الأصلي">
يدعم Moonshot Kimi وضع thinking أصليًا ثنائيًا:
- `thinking: { type: "enabled" }`
- `thinking: { type: "disabled" }`
@ -319,21 +320,21 @@ Moonshot وKimi Coding هما **مزوّدان منفصلان**. المفاتي
}
```
كما يربط OpenClaw مستويات `/think` في وقت التشغيل من أجل Moonshot:
يربط OpenClaw أيضًا مستويات `/think` وقت التشغيل لـ Moonshot:
| مستوى `/think` | سلوك Moonshot |
| مستوى `/think` | سلوك Moonshot |
| -------------------- | -------------------------- |
| `/think off` | `thinking.type=disabled` |
| أي مستوى غير off | `thinking.type=enabled` |
| أي مستوى غير off | `thinking.type=enabled` |
<Warning>
عندما يكون التفكير في Moonshot مفعّلًا، يجب أن تكون `tool_choice` هي `auto` أو `none`. يقوم OpenClaw بتطبيع قيم `tool_choice` غير المتوافقة إلى `auto` من أجل التوافق.
عند تفعيل thinking في Moonshot، يجب أن تكون `tool_choice` هي `auto` أو `none`. يقوم OpenClaw بتطبيع قيم `tool_choice` غير المتوافقة إلى `auto` من أجل التوافق.
</Warning>
يقبل Kimi K2.6 أيضًا حقلًا اختياريًا `thinking.keep` يتحكم في
يقبل Kimi K2.6 أيضًا الحقل الاختياري `thinking.keep` الذي يتحكم في
الاحتفاظ متعدد الأدوار بـ `reasoning_content`. اضبطه إلى `"all"` للاحتفاظ
بالاستدلال الكامل عبر الأدوار؛ أو احذفه (أو اتركه `null`) لاستخدام
استراتيجية الخادم الافتراضية. ولا يمرّر OpenClaw قيمة `thinking.keep` إلا إلى
بـ reasoning الكامل عبر الأدوار؛ أو احذفه (أو اتركه `null`) لاستخدام
استراتيجية الخادم الافتراضية. لا يمرر OpenClaw قيمة `thinking.keep` إلا لـ
`moonshot/kimi-k2.6` ويزيلها من النماذج الأخرى.
```json5
@ -354,10 +355,10 @@ Moonshot وKimi Coding هما **مزوّدان منفصلان**. المفاتي
</Accordion>
<Accordion title="تنقية معرّفات استدعاء الأدوات">
يقدّم Moonshot Kimi معرّفات `tool_call` أصلية على شكل `functions.<name>:<index>` عبر النقل المتوافق مع OpenAI. ولم يعد OpenClaw ينقّي هذه المعرّفات بشكل صارم من أجل Moonshot، بحيث تواصل التدفقات متعددة الأدوار للوكلاء عبر Kimi K2.6 العمل بعد جولتين أو ثلاث من استدعاءات الأدوات عندما تطابق طبقة التقديم المعرفات المشوّهة مع تعريفات الأدوات الأصلية.
<Accordion title="تنقية معرّف استدعاء الأداة">
يقدّم Moonshot Kimi معرّفات tool_call بالشكل `functions.<name>:<index>`. ويحافظ OpenClaw عليها كما هي بحيث تستمر استدعاءات الأدوات متعددة الأدوار في العمل.
إذا احتاج مزوّد مخصص متوافق مع OpenAI إلى السلوك السابق، فاضبط `sanitizeToolCallIds: true` على إدخال المزوّد. توجد هذه العلامة على عائلة replay المشتركة `openai-compatible`؛ وقد تم توصيل Moonshot افتراضيًا بحالة إلغاء الاشتراك.
لفرض التنقية الصارمة على مزوّد مخصص متوافق مع OpenAI، اضبط `sanitizeToolCallIds: true`:
```json5
{
@ -375,29 +376,29 @@ Moonshot وKimi Coding هما **مزوّدان منفصلان**. المفاتي
</Accordion>
<Accordion title="توافق استخدام البث">
تعلن نقاط نهاية Moonshot الأصلية (`https://api.moonshot.ai/v1` و
`https://api.moonshot.cn/v1`) عن توافق استخدام البث على
النقل المشترك `openai-completions`. ويقوم OpenClaw بربط ذلك بإمكانات نقطة النهاية،
لذلك ترث معرّفات المزوّدات المخصصة المتوافقة التي تستهدف مضيفات Moonshot الأصلية نفسها
سلوك استخدام البث نفسه.
تعلن نقاط النهاية الأصلية لـ Moonshot ‏(`https://api.moonshot.ai/v1` و
`https://api.moonshot.cn/v1`) عن توافق streaming usage على
نقل `openai-completions` المشترك. يربط OpenClaw ذلك بإمكانات نقطة النهاية،
لذلك ترث معرّفات المزودات المخصصة المتوافقة التي تستهدف نفس مضيفي Moonshot
الأصليين سلوك streaming-usage نفسه.
ومع التسعير المضمّن لـ K2.6، فإن استخدام البث الذي يتضمن رموز الإدخال والإخراج
ورموز قراءة cache يتحول أيضًا إلى تكلفة محلية تقديرية بالدولار الأمريكي لأوامر
`/status` و`/usage full` و`/usage cost` ولمحاسبة الجلسات المدعومة بـ transcript.
ومع تسعير K2.6 المضمّن، يتم أيضًا تحويل usage المتدفقة التي تتضمن tokens الإدخال
والإخراج وقراءة cache إلى تكلفة محلية تقديرية بالدولار الأمريكي من أجل
`/status` و`/usage full` و`/usage cost` ومحاسبة الجلسة المدعومة بالسجل.
</Accordion>
<Accordion title="مرجع نقطة النهاية ومرجع النموذج">
| المزوّد | بادئة مرجع النموذج | نقطة النهاية | متغير بيئة المصادقة |
| ------- | ------------------ | ------------ | ------------------- |
| Moonshot | `moonshot/` | `https://api.moonshot.ai/v1` | `MOONSHOT_API_KEY` |
| Moonshot CN | `moonshot/` | `https://api.moonshot.cn/v1` | `MOONSHOT_API_KEY` |
| Kimi Coding | `kimi/` | نقطة نهاية Kimi Coding | `KIMI_API_KEY` |
| البحث على الويب | N/A | مثل منطقة Moonshot API نفسها | `KIMI_API_KEY` أو `MOONSHOT_API_KEY` |
| المزوّد | بادئة مرجع النموذج | نقطة النهاية | متغير env للمصادقة |
| ---------- | ---------------- | ----------------------------- | ------------------- |
| Moonshot | `moonshot/` | `https://api.moonshot.ai/v1` | `MOONSHOT_API_KEY` |
| Moonshot CN| `moonshot/` | `https://api.moonshot.cn/v1` | `MOONSHOT_API_KEY` |
| Kimi Coding| `kimi/` | نقطة نهاية Kimi Coding | `KIMI_API_KEY` |
| بحث الويب | N/A | نفس منطقة Moonshot API | `KIMI_API_KEY` أو `MOONSHOT_API_KEY` |
- يستخدم البحث على الويب في Kimi المفتاح `KIMI_API_KEY` أو `MOONSHOT_API_KEY`، ويكون افتراضيًا على `https://api.moonshot.ai/v1` مع النموذج `kimi-k2.6`.
- تجاوز بيانات التسعير والسياق الوصفية في `models.providers` عند الحاجة.
- إذا نشرت Moonshot حدود سياق مختلفة لنموذج ما، فعدّل `contextWindow` وفقًا لذلك.
- يستخدم بحث الويب في Kimi القيمة `KIMI_API_KEY` أو `MOONSHOT_API_KEY`، ويكون افتراضيًا على `https://api.moonshot.ai/v1` مع النموذج `kimi-k2.6`.
- تجاوز بيانات التسعير وبيانات السياق الوصفية في `models.providers` عند الحاجة.
- إذا نشرت Moonshot حدود سياق مختلفة لنموذج ما، فاضبط `contextWindow` وفقًا لذلك.
</Accordion>
</AccordionGroup>
@ -406,13 +407,13 @@ Moonshot وKimi Coding هما **مزوّدان منفصلان**. المفاتي
<CardGroup cols={2}>
<Card title="اختيار النموذج" href="/ar/concepts/model-providers" icon="layers">
اختيار المزوّدين ومراجع النماذج وسلوك الرجوع الاحتياطي.
اختيار المزودات، ومراجع النماذج، وسلوك failover.
</Card>
<Card title="البحث على الويب" href="/ar/tools/web" icon="magnifying-glass">
إعداد مزوّدي البحث على الويب بما في ذلك Kimi.
<Card title="بحث الويب" href="/ar/tools/web" icon="magnifying-glass">
تهيئة مزودات بحث الويب بما في ذلك Kimi.
</Card>
<Card title="مرجع الإعدادات" href="/ar/gateway/configuration-reference" icon="gear">
مخطط الإعدادات الكامل للمزوّدين والنماذج وPlugins.
مخطط config الكامل للمزودات والنماذج وPlugins.
</Card>
<Card title="Moonshot Open Platform" href="https://platform.moonshot.ai" icon="globe">
إدارة مفاتيح Moonshot API والوثائق.

393
docs/ar/providers/openai.md
View File

@ -1,42 +1,42 @@
---
read_when:
- أنت تريد استخدام نماذج OpenAI في OpenClaw
- أنت تريد مصادقة اشتراك Codex بدلًا من مفاتيح API
- أنت تحتاج إلى سلوك تنفيذ أكثر صرامة لوكلاء GPT-5
- تريد استخدام نماذج OpenAI في OpenClaw
- تريد مصادقة اشتراك Codex بدلًا من مفاتيح API
- تحتاج إلى سلوك تنفيذ أكثر صرامة لوكلاء GPT-5
summary: استخدم OpenAI عبر مفاتيح API أو اشتراك Codex في OpenClaw
title: OpenAI
x-i18n:
generated_at: "2026-04-23T07:31:49Z"
generated_at: "2026-04-23T14:02:09Z"
model: gpt-5.4
provider: openai
source_hash: c3d847e53c2faee5363071dfdcb1f4150b64577674161e000844f579482198d1
source_hash: ac42660234e1971440f6de3b04adb1d3a1fddca20219fb68936c36e4c2f95265
source_path: providers/openai.md
workflow: 15
---
# OpenAI
توفر OpenAI واجهات API للمطورين لنماذج GPT. يدعم OpenClaw مساري مصادقة:
توفّر OpenAI واجهات API للمطورين لنماذج GPT. يدعم OpenClaw مسارين للمصادقة:
- **مفتاح API** — وصول مباشر إلى OpenAI Platform مع فوترة حسب الاستخدام (نماذج `openai/*`)
- **اشتراك Codex** — تسجيل دخول ChatGPT/Codex مع وصول عبر الاشتراك (نماذج `openai-codex/*`)
- **مفتاح API** — وصول مباشر إلى OpenAI Platform مع فوترة حسب الاستخدام (لنماذج `openai/*`)
- **اشتراك Codex** — تسجيل دخول ChatGPT/Codex مع وصول عبر الاشتراك (لنماذج `openai-codex/*`)
تدعم OpenAI صراحةً استخدام OAuth الخاص بالاشتراك في الأدوات وسير العمل الخارجية مثل OpenClaw.
## تغطية ميزات OpenClaw
| قدرة OpenAI | سطح OpenClaw | الحالة |
| قدرات OpenAI | سطح OpenClaw | الحالة |
| ------------------------- | ----------------------------------------- | ------------------------------------------------------ |
| الدردشة / Responses | موفر النماذج `openai/<model>` | نعم |
| نماذج اشتراك Codex | موفر النماذج `openai-codex/<model>` | نعم |
| البحث على الويب من جانب الخادم | أداة OpenAI Responses الأصلية | نعم، عند تفعيل البحث على الويب وعدم تثبيت موفر محدد |
| الصور | `image_generate` | نعم |
| الفيديو | `video_generate` | نعم |
| تحويل النص إلى كلام | `messages.tts.provider: "openai"` / `tts` | نعم |
| تحويل الكلام إلى نص على دفعات | `tools.media.audio` / فهم الوسائط | نعم |
| تحويل الكلام إلى نص بشكل متدفق | Voice Call `streaming.provider: "openai"` | نعم |
| الصوت الفوري | Voice Call `realtime.provider: "openai"` | نعم |
| التضمينات | موفر تضمينات الذاكرة | نعم |
| الدردشة / Responses | موفر النموذج `openai/<model>` | نعم |
| نماذج اشتراك Codex | موفر النموذج `openai-codex/<model>` | نعم |
| البحث على الويب من جهة الخادم | أداة OpenAI Responses الأصلية | نعم، عندما يكون بحث الويب مفعّلًا ولا يوجد موفر مثبّت |
| الصور | `image_generate` | نعم |
| الفيديو | `video_generate` | نعم |
| تحويل النص إلى كلام | `messages.tts.provider: "openai"` / `tts` | نعم |
| تحويل الكلام إلى نص دفعةً واحدة | `tools.media.audio` / فهم الوسائط | نعم |
| تحويل الكلام إلى نص بالبث | Voice Call `streaming.provider: "openai"` | نعم |
| الصوت الآني | Voice Call `realtime.provider: "openai"` | نعم |
| التضمينات | موفر تضمينات الذاكرة | نعم |
## البدء
@ -44,13 +44,13 @@ x-i18n:
<Tabs>
<Tab title="مفتاح API (OpenAI Platform)">
**الأفضل من أجل:** وصول API مباشر وفوترة حسب الاستخدام.
**الأفضل لـ:** وصول API المباشر والفوترة حسب الاستخدام.
<Steps>
<Step title="احصل على مفتاح API الخاص بك">
أنشئ أو انسخ مفتاح API من [لوحة تحكم OpenAI Platform](https://platform.openai.com/api-keys).
أنشئ مفتاح API أو انسخه من [لوحة تحكم OpenAI Platform](https://platform.openai.com/api-keys).
</Step>
<Step title="شغّل onboarding">
<Step title="شغّل الإعداد الأولي">
```bash
openclaw onboard --auth-choice openai-api-key
```
@ -72,11 +72,11 @@ x-i18n:
| مرجع النموذج | المسار | المصادقة |
|-----------|-------|------|
| `openai/gpt-5.4` | OpenAI Platform API مباشرة | `OPENAI_API_KEY` |
| `openai/gpt-5.4-pro` | OpenAI Platform API مباشرة | `OPENAI_API_KEY` |
| `openai/gpt-5.4` | OpenAI Platform API مباشر | `OPENAI_API_KEY` |
| `openai/gpt-5.4-pro` | OpenAI Platform API مباشر | `OPENAI_API_KEY` |
<Note>
يتم توجيه تسجيل دخول ChatGPT/Codex عبر `openai-codex/*`، وليس `openai/*`.
يُوجَّه تسجيل دخول ChatGPT/Codex عبر `openai-codex/*` وليس `openai/*`.
</Note>
### مثال على التكوين
@ -89,16 +89,16 @@ x-i18n:
```
<Warning>
لا يكشف OpenClaw **عن** `openai/gpt-5.3-codex-spark` على مسار API المباشر. إذ ترفض طلبات OpenAI API الحية هذا النموذج. إن Spark خاص بـ Codex فقط.
لا يعرّض OpenClaw **مطلقًا** `openai/gpt-5.3-codex-spark` على مسار API المباشر. ترفض طلبات OpenAI API الحية ذلك النموذج. Spark مخصص لـ Codex فقط.
</Warning>
</Tab>
<Tab title="اشتراك Codex">
**الأفضل من أجل:** استخدام اشتراك ChatGPT/Codex الخاص بك بدلًا من مفتاح API منفصل. يتطلب Codex السحابي تسجيل الدخول إلى ChatGPT.
**الأفضل لـ:** استخدام اشتراك ChatGPT/Codex الخاص بك بدلًا من مفتاح API منفصل. يتطلب Codex السحابي تسجيل دخول ChatGPT.
<Steps>
<Step title="شغّل OAuth الخاص بـ Codex">
<Step title="شغّل Codex OAuth">
```bash
openclaw onboard --auth-choice openai-codex
```
@ -109,13 +109,13 @@ x-i18n:
openclaw models auth login --provider openai-codex
```
بالنسبة إلى الإعدادات الرأسية أو غير الملائمة لرد الاتصال، أضف `--device-code` لتسجيل الدخول باستخدام تدفق رمز الجهاز في ChatGPT بدلًا من رد الاتصال عبر المتصفح المحلي:
بالنسبة للإعدادات دون واجهة أو غير الملائمة لرد نداءات callback، أضف `--device-code` لتسجيل الدخول باستخدام تدفق رمز الجهاز الخاص بـ ChatGPT بدلًا من رد نداء المتصفح المحلي:
```bash
openclaw models auth login --provider openai-codex --device-code
```
</Step>
<Step title="اضبط النموذج الافتراضي">
<Step title="عيّن النموذج الافتراضي">
```bash
openclaw config set agents.defaults.model.primary openai-codex/gpt-5.4
```
@ -132,7 +132,7 @@ x-i18n:
| مرجع النموذج | المسار | المصادقة |
|-----------|-------|------|
| `openai-codex/gpt-5.4` | ChatGPT/Codex OAuth | تسجيل دخول Codex |
| `openai-codex/gpt-5.3-codex-spark` | ChatGPT/Codex OAuth | تسجيل دخول Codex (يعتمد على الاستحقاق) |
| `openai-codex/gpt-5.3-codex-spark` | ChatGPT/Codex OAuth | تسجيل دخول Codex (بحسب الاستحقاق) |
<Note>
هذا المسار منفصل عمدًا عن `openai/gpt-5.4`. استخدم `openai/*` مع مفتاح API للوصول المباشر إلى Platform، واستخدم `openai-codex/*` للوصول عبر اشتراك Codex.
@ -147,19 +147,19 @@ x-i18n:
```
<Note>
لم يعد onboarding يستورد مواد OAuth من `~/.codex`. سجّل الدخول باستخدام OAuth عبر المتصفح (الافتراضي) أو تدفق رمز الجهاز أعلاه — ويتولى OpenClaw إدارة بيانات الاعتماد الناتجة داخل مخزن مصادقة الوكيل الخاص به.
لم يعد الإعداد الأولي يستورد مواد OAuth من `~/.codex`. سجّل الدخول باستخدام OAuth عبر المتصفح (الافتراضي) أو تدفق رمز الجهاز أعلاه — يدير OpenClaw بيانات الاعتماد الناتجة في مخزن مصادقة agent الخاص به.
</Note>
### حد نافذة السياق
يتعامل OpenClaw مع بيانات وصفية النموذج وحد بيئة التشغيل للسياق كقيمتين منفصلتين.
يتعامل OpenClaw مع بيانات النموذج الوصفية وحد السياق وقت التشغيل باعتبارهما قيمتين منفصلتين.
بالنسبة إلى `openai-codex/gpt-5.4`:
- `contextWindow` الأصلية: `1050000`
- الحد الافتراضي لـ `contextTokens` في بيئة التشغيل: `272000`
- `contextWindow` الأصلي: `1050000`
- الحد الافتراضي لـ `contextTokens` في وقت التشغيل: `272000`
يتمتع الحد الافتراضي الأصغر بزمن استجابة أفضل وخصائص جودة أفضل عمليًا. يمكنك تجاوزه باستخدام `contextTokens`:
يتمتع الحد الافتراضي الأصغر بخصائص أفضل عمليًا من حيث زمن الاستجابة والجودة. ويمكنك تجاوزه باستخدام `contextTokens`:
```json5
{
@ -174,23 +174,23 @@ x-i18n:
```
<Note>
استخدم `contextWindow` للتصريح ببيانات النموذج الأصلية الوصفية. واستخدم `contextTokens` لتقييد ميزانية سياق بيئة التشغيل.
استخدم `contextWindow` للتصريح ببيانات النموذج الوصفية الأصلية. واستخدم `contextTokens` لتقييد ميزانية السياق في وقت التشغيل.
</Note>
</Tab>
</Tabs>
## توليد الصور
## إنشاء الصور
يسجل Plugin `openai` المضمّن توليد الصور عبر الأداة `image_generate`.
يسجّل Plugin ‏`openai` المضمّن إنشاء الصور عبر الأداة `image_generate`.
| القدرة | القيمة |
| ------------------------- | ---------------------------------- |
| النموذج الافتراضي | `openai/gpt-image-2` |
| الحد الأقصى للصور في كل طلب | 4 |
| وضع التعديل | مفعّل (حتى 5 صور مرجعية) |
| تجاوزات الحجم | مدعومة، بما في ذلك أحجام 2K/4K |
| نسبة الأبعاد / الدقة | لا يتم تمريرها إلى OpenAI Images API |
| القدرة | القيمة |
| ----------------------- | ---------------------------------- |
| النموذج الافتراضي | `openai/gpt-image-2` |
| الحد الأقصى للصور لكل طلب | 4 |
| وضع التحرير | مفعّل (حتى 5 صور مرجعية) |
| تجاوزات الحجم | مدعومة، بما في ذلك أحجام 2K/4K |
| نسبة العرض إلى الارتفاع / الدقة | لا تُمرَّر إلى OpenAI Images API |
```json5
{
@ -203,36 +203,34 @@ x-i18n:
```
<Note>
راجع [Image Generation](/ar/tools/image-generation) للاطلاع على معلمات الأداة المشتركة، واختيار الموفّر، وسلوك failover.
راجع [إنشاء الصور](/ar/tools/image-generation) لمعلمات الأدوات المشتركة، واختيار الموفّر، وسلوك تجاوز الفشل.
</Note>
إن `gpt-image-2` هو الافتراضي لكل من توليد الصور من النص في OpenAI وتحرير الصور.
ولا يزال `gpt-image-1` قابلًا للاستخدام كتجاوز صريح للنموذج، لكن
مسارات عمل الصور الجديدة في OpenAI ينبغي أن تستخدم `openai/gpt-image-2`.
`gpt-image-2` هو الافتراضي لكل من إنشاء الصور من النص في OpenAI وتحرير الصور. ويظل `gpt-image-1` قابلًا للاستخدام كتجاوز صريح للنموذج، لكن تدفقات عمل الصور الجديدة في OpenAI يجب أن تستخدم `openai/gpt-image-2`.
توليد:
إنشاء:
```
/tool image_generate model=openai/gpt-image-2 prompt="A polished launch poster for OpenClaw on macOS" size=3840x2160 count=1
```
تعديل:
تحرير:
```
/tool image_generate model=openai/gpt-image-2 prompt="Preserve the object shape, change the material to translucent glass" image=/path/to/reference.png size=1024x1536
```
## توليد الفيديو
## إنشاء الفيديو
يسجل Plugin `openai` المضمّن توليد الفيديو عبر الأداة `video_generate`.
يسجّل Plugin ‏`openai` المضمّن إنشاء الفيديو عبر الأداة `video_generate`.
| القدرة | القيمة |
| القدرة | القيمة |
| ---------------- | --------------------------------------------------------------------------------- |
| النموذج الافتراضي | `openai/sora-2` |
| الأوضاع | نص إلى فيديو، صورة إلى فيديو، تحرير فيديو واحد |
| المدخلات المرجعية | صورة واحدة أو فيديو واحد |
| تجاوزات الحجم | مدعومة |
| تجاوزات أخرى | يتم تجاهل `aspectRatio` و`resolution` و`audio` و`watermark` مع تحذير من الأداة |
| النموذج الافتراضي | `openai/sora-2` |
| الأوضاع | تحويل النص إلى فيديو، وتحويل الصورة إلى فيديو، وتحرير فيديو واحد |
| المدخلات المرجعية | صورة واحدة أو فيديو واحد |
| تجاوزات الحجم | مدعومة |
| تجاوزات أخرى | يتم تجاهل `aspectRatio` و`resolution` و`audio` و`watermark` مع تحذير من الأداة |
```json5
{
@ -245,25 +243,25 @@ x-i18n:
```
<Note>
راجع [Video Generation](/ar/tools/video-generation) للاطلاع على معلمات الأداة المشتركة، واختيار الموفّر، وسلوك failover.
راجع [إنشاء الفيديو](/ar/tools/video-generation) لمعلمات الأدوات المشتركة، واختيار الموفّر، وسلوك تجاوز الفشل.
</Note>
## مساهمة prompt الخاصة بـ GPT-5
## مساهمة موجه GPT-5
يضيف OpenClaw مساهمة prompt مشتركة خاصة بـ GPT-5 لتشغيلات عائلة GPT-5 عبر الموفّرين. وهي تُطبّق حسب معرّف النموذج، لذا تتلقى `openai/gpt-5.4` و`openai-codex/gpt-5.4` و`openrouter/openai/gpt-5.4` و`opencode/gpt-5.4` وغيرها من مراجع GPT-5 المتوافقة التراكب نفسه. أما النماذج الأقدم GPT-4.x فلا تتلقى ذلك.
يضيف OpenClaw مساهمة موجه مشتركة لـ GPT-5 لتشغيلات عائلة GPT-5 عبر الموفّرين. وهي تُطبَّق بحسب معرّف النموذج، لذلك تتلقى `openai/gpt-5.4` و`openai-codex/gpt-5.4` و`openrouter/openai/gpt-5.4` و`opencode/gpt-5.4` ومراجع GPT-5 المتوافقة الأخرى الطبقة نفسها. أما نماذج GPT-4.x الأقدم فلا تتلقاها.
يستخدم موفّر Codex harness الأصلي المضمّن (`codex/*`) سلوك GPT-5 نفسه وتراكب Heartbeat عبر تعليمات المطور في Codex app-server، لذلك تحافظ جلسات `codex/gpt-5.x` على المتابعة نفسها وإرشادات Heartbeat الاستباقية نفسها رغم أن Codex يملك بقية prompt الخاصة بالـ harness.
يستخدم موفّر حزمة Codex الأصلية المضمّن (`codex/*`) سلوك GPT-5 نفسه وطبقة Heartbeat نفسها عبر تعليمات المطوّر الخاصة بخادم تطبيق Codex، لذا تحافظ جلسات `codex/gpt-5.x` على الإرشادات نفسها الخاصة بالمتابعة والتصرف الاستباقي عبر Heartbeat، رغم أن Codex يملك بقية موجه الحزمة.
تضيف مساهمة GPT-5 عقد سلوك موسومًا يتعلق باستمرارية الشخصية، وسلامة التنفيذ، وانضباط الأدوات، وشكل المخرجات، وفحوصات الإكمال، والتحقق. أما سلوك الرد الخاص بالقناة وسلوك الرسائل الصامتة فيبقيان في system prompt المشترك لـ OpenClaw وسياسة التسليم الصادرة. تكون إرشادات GPT-5 مفعّلة دائمًا للنماذج المطابقة. أما طبقة أسلوب التفاعل الودّي فهي منفصلة وقابلة للتكوين.
تضيف مساهمة GPT-5 عقد سلوك موسومًا للاستمرار في الشخصية، وسلامة التنفيذ، وانضباط الأدوات، وشكل المخرجات، وفحوصات الإكمال، والتحقق. ويظل سلوك الرد الخاص بالقناة وسلوك الرسائل الصامتة ضمن موجه النظام المشترك لـ OpenClaw وسياسة التسليم الصادرة. وتكون إرشادات GPT-5 مفعّلة دائمًا للنماذج المطابقة. أما طبقة أسلوب التفاعل الودّي فهي منفصلة وقابلة للتكوين.
| القيمة | التأثير |
| القيمة | التأثير |
| ---------------------- | ------------------------------------------- |
| `"friendly"` (الافتراضي) | تفعيل طبقة أسلوب التفاعل الودّي |
| `"on"` | اسم مستعار لـ `"friendly"` |
| `"off"` | تعطيل طبقة الأسلوب الودّي فقط |
| `"friendly"` (افتراضي) | تفعيل طبقة أسلوب التفاعل الودّي |
| `"on"` | اسم مستعار لـ `"friendly"` |
| `"off"` | تعطيل طبقة الأسلوب الودّي فقط |
<Tabs>
<Tab title="التكوين">
<Tab title="Config">
```json5
{
agents: {
@ -284,30 +282,30 @@ x-i18n:
</Tabs>
<Tip>
تكون القيم غير حساسة لحالة الأحرف وقت التشغيل، لذا فإن `"Off"` و`"off"` كلتاهما تعطلان طبقة الأسلوب الودّي.
القيم غير حساسة لحالة الأحرف في وقت التشغيل، لذا فإن `"Off"` و`"off"` كلتاهما تعطّلان طبقة الأسلوب الودّي.
</Tip>
<Note>
لا يزال `plugins.entries.openai.config.personality` القديم مقروءًا كرجوع احتياطي للتوافق عندما لا يكون الإعداد المشترك `agents.defaults.promptOverlays.gpt5.personality` مضبوطًا.
لا يزال `plugins.entries.openai.config.personality` القديم مقروءًا كخيار توافق احتياطي عندما لا يكون الإعداد المشترك `agents.defaults.promptOverlays.gpt5.personality` مضبوطًا.
</Note>
## الصوت والكلام
<AccordionGroup>
<Accordion title="توليف الكلام (TTS)">
يسجل Plugin `openai` المضمّن توليف الكلام لسطح `messages.tts`.
<Accordion title="تركيب الكلام (TTS)">
يسجّل Plugin ‏`openai` المضمّن تركيب الكلام لسطح `messages.tts`.
| الإعداد | مسار التكوين | الافتراضي |
|---------|------------|---------|
| النموذج | `messages.tts.providers.openai.model` | `gpt-4o-mini-tts` |
| الصوت | `messages.tts.providers.openai.voice` | `coral` |
| السرعة | `messages.tts.providers.openai.speed` | (غير مضبوط) |
| التعليمات | `messages.tts.providers.openai.instructions` | (غير مضبوط، لـ `gpt-4o-mini-tts` فقط) |
| التعليمات | `messages.tts.providers.openai.instructions` | (غير مضبوط، `gpt-4o-mini-tts` فقط) |
| التنسيق | `messages.tts.providers.openai.responseFormat` | `opus` للملاحظات الصوتية، و`mp3` للملفات |
| مفتاح API | `messages.tts.providers.openai.apiKey` | يرجع إلى `OPENAI_API_KEY` |
| مفتاح API | `messages.tts.providers.openai.apiKey` | يعود إلى `OPENAI_API_KEY` |
| Base URL | `messages.tts.providers.openai.baseUrl` | `https://api.openai.com/v1` |
النماذج المتاحة: `gpt-4o-mini-tts`, `tts-1`, `tts-1-hd`. الأصوات المتاحة: `alloy`, `ash`, `ballad`, `cedar`, `coral`, `echo`, `fable`, `juniper`, `marin`, `onyx`, `nova`, `sage`, `shimmer`, `verse`.
النماذج المتاحة: `gpt-4o-mini-tts` و`tts-1` و`tts-1-hd`. والأصوات المتاحة: `alloy` و`ash` و`ballad` و`cedar` و`coral` و`echo` و`fable` و`juniper` و`marin` و`onyx` و`nova` و`sage` و`shimmer` و`verse`.
```json5
{
@ -322,23 +320,23 @@ x-i18n:
```
<Note>
اضبط `OPENAI_TTS_BASE_URL` لتجاوز عنوان TTS الأساسي من دون التأثير في نقطة نهاية Chat API.
اضبط `OPENAI_TTS_BASE_URL` لتجاوز عنوان Base URL الخاص بـ TTS من دون التأثير في نقطة نهاية chat API.
</Note>
</Accordion>
<Accordion title="تحويل الكلام إلى نص">
يسجل Plugin `openai` المضمّن تحويل الكلام إلى نص على دفعات عبر
سطح التحويل إلى نص لفهم الوسائط في OpenClaw.
يسجّل Plugin ‏`openai` المضمّن تحويل الكلام إلى نص على دفعات عبر
سطح النسخ الخاص بفهم الوسائط في OpenClaw.
- النموذج الافتراضي: `gpt-4o-transcribe`
- نقطة النهاية: OpenAI REST ‏`/v1/audio/transcriptions`
- مسار الإدخال: رفع ملف صوتي بنموذج multipart
- مدعوم في OpenClaw أينما كان تحويل الصوت الوارد إلى نص يستخدم
- نقطة النهاية: ‏OpenAI REST ‏`/v1/audio/transcriptions`
- مسار الإدخال: رفع ملف صوتي متعدد الأجزاء
- مدعوم في OpenClaw أينما كان نسخ الصوت الوارد يستخدم
`tools.media.audio`، بما في ذلك مقاطع قنوات Discord الصوتية ومرفقات
الصوت في القنوات
لفرض استخدام OpenAI لتحويل الصوت الوارد إلى نص:
لفرض OpenAI لنسخ الصوت الوارد:
```json5
{
@ -358,31 +356,31 @@ x-i18n:
}
```
تُمرر تلميحات اللغة وprompt إلى OpenAI عندما يوفّرها
تكوين وسائط الصوت المشترك أو طلب التحويل إلى نص لكل استدعاء.
تُمرَّر تلميحات اللغة والموجه إلى OpenAI عند توفيرها بواسطة
إعداد الوسائط الصوتية المشترك أو طلب النسخ لكل استدعاء.
</Accordion>
<Accordion title="التحويل الفوري إلى نص">
يسجل Plugin `openai` المضمّن التحويل الفوري إلى نص من أجل Plugin الخاص بـ Voice Call.
<Accordion title="النسخ الفوري">
يسجّل Plugin ‏`openai` المضمّن النسخ الفوري لPlugin ‏Voice Call.
| الإعداد | مسار التكوين | الافتراضي |
|---------|------------|---------|
| النموذج | `plugins.entries.voice-call.config.streaming.providers.openai.model` | `gpt-4o-transcribe` |
| اللغة | `...openai.language` | (غير مضبوط) |
| Prompt | `...openai.prompt` | (غير مضبوط) |
| الموجه | `...openai.prompt` | (غير مضبوط) |
| مدة الصمت | `...openai.silenceDurationMs` | `800` |
| عتبة VAD | `...openai.vadThreshold` | `0.5` |
| مفتاح API | `...openai.apiKey` | يرجع إلى `OPENAI_API_KEY` |
| مفتاح API | `...openai.apiKey` | يعود إلى `OPENAI_API_KEY` |
<Note>
يستخدم اتصال WebSocket إلى `wss://api.openai.com/v1/realtime` مع صوت G.711 u-law ‏(`g711_ulaw` / `audio/pcmu`). موفر البث هذا مخصص لمسار التحويل الفوري إلى نص في Voice Call؛ أما صوت Discord فيسجل حاليًا مقاطع قصيرة ويستخدم بدلًا من ذلك مسار التحويل على دفعات `tools.media.audio`.
يستخدم اتصال WebSocket إلى `wss://api.openai.com/v1/realtime` مع صوت G.711 u-law (`g711_ulaw` / `audio/pcmu`). موفر البث هذا مخصص لمسار النسخ الفوري في Voice Call؛ أما الصوت في Discord فيسجّل حاليًا مقاطع قصيرة ويستخدم بدلًا من ذلك مسار النسخ الدفعي `tools.media.audio`.
</Note>
</Accordion>
<Accordion title="الصوت الفوري">
يسجل Plugin `openai` المضمّن الصوت الفوري من أجل Plugin الخاص بـ Voice Call.
يسجّل Plugin ‏`openai` المضمّن الصوت الفوري لPlugin ‏Voice Call.
| الإعداد | مسار التكوين | الافتراضي |
|---------|------------|---------|
@ -391,30 +389,155 @@ x-i18n:
| درجة الحرارة | `...openai.temperature` | `0.8` |
| عتبة VAD | `...openai.vadThreshold` | `0.5` |
| مدة الصمت | `...openai.silenceDurationMs` | `500` |
| مفتاح API | `...openai.apiKey` | يرجع إلى `OPENAI_API_KEY` |
| مفتاح API | `...openai.apiKey` | يعود إلى `OPENAI_API_KEY` |
<Note>
يدعم Azure OpenAI عبر مفاتيح التكوين `azureEndpoint` و`azureDeployment`. ويدعم الاستدعاء ثنائي الاتجاه للأدوات. ويستخدم تنسيق الصوت G.711 u-law.
يدعم Azure OpenAI عبر مفاتيح التكوين `azureEndpoint` و`azureDeployment`. ويدعم استدعاء الأدوات ثنائي الاتجاه. ويستخدم تنسيق الصوت G.711 u-law.
</Note>
</Accordion>
</AccordionGroup>
## نقاط نهاية Azure OpenAI
يمكن لموفّر `openai` المضمّن استهداف مورد Azure OpenAI من أجل
إنشاء الصور عبر تجاوز عنوان Base URL. وعلى مسار إنشاء الصور، يكتشف OpenClaw
أسماء مضيفي Azure على `models.providers.openai.baseUrl` وينتقل إلى
صيغة طلب Azure تلقائيًا.
<Note>
يستخدم الصوت الفوري مسار تكوين منفصلًا
(`plugins.entries.voice-call.config.realtime.providers.openai.azureEndpoint`)
ولا يتأثر بـ `models.providers.openai.baseUrl`. راجع أكورديون **الصوت
الفوري** ضمن [الصوت والكلام](#voice-and-speech) لمعرفة إعدادات Azure
الخاصة به.
</Note>
استخدم Azure OpenAI عندما:
- يكون لديك بالفعل اشتراك Azure OpenAI، أو حصة، أو اتفاقية مؤسسية
- تحتاج إلى إقامة بيانات إقليمية أو ضوابط امتثال توفرها Azure
- تريد إبقاء حركة المرور داخل مستأجر Azure موجود
### التكوين
لإنشاء الصور عبر Azure من خلال موفّر `openai` المضمّن، وجّه
`models.providers.openai.baseUrl` إلى مورد Azure الخاص بك واضبط `apiKey` على
مفتاح Azure OpenAI (وليس مفتاح OpenAI Platform):
```json5
{
models: {
providers: {
openai: {
baseUrl: "https://<your-resource>.openai.azure.com",
apiKey: "<azure-openai-api-key>",
},
},
},
}
```
يتعرف OpenClaw على لاحقات مضيف Azure التالية لمسار Azure الخاص بإنشاء الصور:
- `*.openai.azure.com`
- `*.services.ai.azure.com`
- `*.cognitiveservices.azure.com`
وبالنسبة إلى طلبات إنشاء الصور على مضيف Azure معروف، يقوم OpenClaw بما يلي:
- يرسل الترويسة `api-key` بدلًا من `Authorization: Bearer`
- يستخدم مسارات مقيّدة بالنشر (`/openai/deployments/{deployment}/...`)
- يضيف `?api-version=...` إلى كل طلب
أما عناوين Base URL الأخرى (OpenAI العامة، وواجهات proxy المتوافقة مع OpenAI) فتبقي
صيغة طلب الصور القياسية الخاصة بـ OpenAI.
<Note>
يتطلب توجيه Azure لمسار إنشاء الصور في موفّر `openai`
OpenClaw 2026.4.22 أو أحدث. أما الإصدارات الأقدم فتتعامل مع أي
`openai.baseUrl` مخصص مثل نقطة نهاية OpenAI العامة وستفشل مع عمليات نشر
الصور في Azure.
</Note>
### إصدار API
اضبط `AZURE_OPENAI_API_VERSION` لتثبيت إصدار Azure معاينة أو GA محدد
لمسار إنشاء الصور عبر Azure:
```bash
export AZURE_OPENAI_API_VERSION="2024-12-01-preview"
```
القيمة الافتراضية هي `2024-12-01-preview` عندما لا يكون المتغير مضبوطًا.
### أسماء النماذج هي أسماء عمليات النشر
يربط Azure OpenAI النماذج بعمليات النشر. وبالنسبة إلى طلبات إنشاء الصور في Azure
الموجّهة عبر موفّر `openai` المضمّن، يجب أن يكون الحقل `model` في OpenClaw
هو **اسم نشر Azure** الذي ضبطته في بوابة Azure، وليس
معرّف نموذج OpenAI العام.
إذا أنشأت عملية نشر باسم `gpt-image-2-prod` تخدم `gpt-image-2`:
```
/tool image_generate model=openai/gpt-image-2-prod prompt="A clean poster" size=1024x1024 count=1
```
وتنطبق قاعدة اسم النشر نفسها على استدعاءات إنشاء الصور الموجّهة عبر
موفّر `openai` المضمّن.
### التوفر الإقليمي
يتوفر إنشاء الصور في Azure حاليًا فقط في مجموعة فرعية من المناطق
(مثل `eastus2` و`swedencentral` و`polandcentral` و`westus3` و
`uaenorth`). راجع قائمة المناطق الحالية من Microsoft قبل إنشاء
عملية نشر، وأكد أن النموذج المحدد متاح في منطقتك.
### اختلافات المعلمات
لا تقبل Azure OpenAI وOpenAI العامة دائمًا معلمات الصور نفسها.
وقد ترفض Azure خيارات تسمح بها OpenAI العامة (مثل بعض قيم
`background` على `gpt-image-2`) أو تتيحها فقط على إصدارات نماذج محددة.
وتأتي هذه الاختلافات من Azure ومن النموذج الأساسي، وليس من
OpenClaw. وإذا فشل طلب Azure بخطأ تحقق، فتحقق من
مجموعة المعلمات المدعومة لعملية النشر المحددة وإصدار API في
بوابة Azure.
<Note>
تستخدم Azure OpenAI سلوك نقل وتوافق أصليًا لكنها لا تتلقى
ترويسات الإسناد المخفية الخاصة بـ OpenClaw. راجع أكورديون **المسارات الأصلية مقابل
المسارات المتوافقة مع OpenAI** ضمن [التكوين المتقدم](#advanced-configuration)
للتفاصيل.
</Note>
<Tip>
للحصول على موفّر Azure OpenAI Responses منفصل (مختلف عن موفّر `openai`)، راجع مراجع `azure-openai-responses/*` في أكورديون [Compaction من جهة الخادم](#server-side-compaction-responses-api).
</Tip>
<Note>
تحتاج حركة Azure الخاصة بالدردشة وResponses إلى إعداد موفّر/API خاص بـ Azure
بالإضافة إلى تجاوز عنوان Base URL. وإذا كنت تريد استدعاءات نماذج Azure تتجاوز إنشاء
الصور، فاستخدم تدفق الإعداد الأولي أو إعداد موفّر يضبط
صيغة Azure API/المصادقة المناسبة بدلًا من افتراض أن `openai.baseUrl` وحده
يكفي.
</Note>
## التكوين المتقدم
<AccordionGroup>
<Accordion title="النقل (WebSocket مقابل SSE)">
يستخدم OpenClaw أسلوب WebSocket أولًا مع رجوع SSE الاحتياطي (`"auto"`) لكل من `openai/*` و`openai-codex/*`.
يستخدم OpenClaw وضع WebSocket أولًا مع رجوع إلى SSE (`"auto"`) لكل من `openai/*` و`openai-codex/*`.
في وضع `"auto"`، يقوم OpenClaw بما يلي:
- يعيد محاولة فشل مبكر واحد في WebSocket قبل الرجوع إلى SSE
- بعد أي فشل، يعلّم WebSocket على أنه متدهور لمدة ~60 ثانية ويستخدم SSE أثناء فترة التهدئة
- يرفق رؤوس هوية جلسة ودور ثابتة لإعادة المحاولات وإعادة الاتصال
- يطبّع عدادات الاستخدام (`input_tokens` / `prompt_tokens`) عبر أشكال النقل المختلفة
- يعيد محاولة فشل WebSocket مبكر واحد قبل الرجوع إلى SSE
- بعد الفشل، يعلّم WebSocket على أنه متدهور لمدة ~60 ثانية ويستخدم SSE أثناء فترة التهدئة
- يرفق ترويسات مستقرة لهوية الجلسة والدور لإعادة المحاولة وإعادة الاتصال
- يطبع عدادات الاستخدام (`input_tokens` / `prompt_tokens`) عبر متغيرات النقل المختلفة
| القيمة | السلوك |
|-------|----------|
| `"auto"` (الافتراضي) | WebSocket أولًا، مع رجوع SSE الاحتياطي |
| `"auto"` (افتراضي) | WebSocket أولًا، مع رجوع إلى SSE |
| `"sse"` | فرض SSE فقط |
| `"websocket"` | فرض WebSocket فقط |
@ -432,9 +555,9 @@ x-i18n:
}
```
مستندات OpenAI ذات الصلة:
- [Realtime API with WebSocket](https://platform.openai.com/docs/guides/realtime-websocket)
- [Streaming API responses (SSE)](https://platform.openai.com/docs/guides/streaming-responses)
وثائق OpenAI ذات الصلة:
- [Realtime API مع WebSocket](https://platform.openai.com/docs/guides/realtime-websocket)
- [استجابات API المتدفقة (SSE)](https://platform.openai.com/docs/guides/streaming-responses)
</Accordion>
@ -461,12 +584,12 @@ x-i18n:
<a id="openai-fast-mode"></a>
<Accordion title="الوضع السريع">
يكشف OpenClaw عن مفتاح وضع سريع مشترك لكل من `openai/*` و`openai-codex/*`:
يوفّر OpenClaw مفتاح تبديل مشتركًا للوضع السريع لكل من `openai/*` و`openai-codex/*`:
- **الدردشة/واجهة المستخدم:** `/fast status|on|off`
- **التكوين:** `agents.defaults.models["<provider>/<model>"].params.fastMode`
عند التفعيل، يربط OpenClaw الوضع السريع بالمعالجة ذات الأولوية في OpenAI ‏(`service_tier = "priority"`). وتُحفَظ قيم `service_tier` الحالية، ولا يعيد الوضع السريع كتابة `reasoning` أو `text.verbosity`.
عند التفعيل، يربط OpenClaw الوضع السريع بالمعالجة ذات الأولوية في OpenAI (`service_tier = "priority"`). وتُحفَظ قيم `service_tier` الحالية، ولا يعيد الوضع السريع كتابة `reasoning` أو `text.verbosity`.
```json5
{
@ -482,13 +605,13 @@ x-i18n:
```
<Note>
تتغلب تجاوزات الجلسة على التكوين. ويؤدي مسح تجاوز الجلسة في واجهة Sessions إلى إعادة الجلسة إلى القيمة الافتراضية المضبوطة.
تتغلب تجاوزات الجلسة على التكوين. وتؤدي إزالة تجاوز الجلسة في واجهة Sessions إلى إعادة الجلسة إلى القيمة الافتراضية المضبوطة.
</Note>
</Accordion>
<Accordion title="المعالجة ذات الأولوية (service_tier)">
تكشف API الخاصة بـ OpenAI عن المعالجة ذات الأولوية عبر `service_tier`. اضبطها لكل نموذج في OpenClaw:
توفّر واجهة OpenAI API المعالجة ذات الأولوية عبر `service_tier`. اضبطها لكل نموذج في OpenClaw:
```json5
{
@ -503,24 +626,24 @@ x-i18n:
}
```
القيم المدعومة: `auto`, `default`, `flex`, `priority`.
القيم المدعومة: `auto` و`default` و`flex` و`priority`.
<Warning>
لا يُمرَّر `serviceTier` إلا إلى نقاط نهاية OpenAI الأصلية (`api.openai.com`) ونقاط نهاية Codex الأصلية (`chatgpt.com/backend-api`). وإذا قمت بتوجيه أي موفر منهما عبر proxy، فإن OpenClaw يترك `service_tier` من دون تعديل.
لا تُمرَّر `serviceTier` إلا إلى نقاط نهاية OpenAI الأصلية (`api.openai.com`) ونقاط نهاية Codex الأصلية (`chatgpt.com/backend-api`). وإذا وجّهت أيًّا من الموفّرين عبر proxy، يترك OpenClaw قيمة `service_tier` دون تعديل.
</Warning>
</Accordion>
<Accordion title="Compaction على جانب الخادم (Responses API)">
بالنسبة إلى نماذج OpenAI Responses المباشرة (`openai/*` على `api.openai.com`)، يفعّل OpenClaw تلقائيًا Compaction على جانب الخادم:
<Accordion title="Compaction من جهة الخادم (Responses API)">
بالنسبة إلى نماذج OpenAI Responses المباشرة (`openai/*` على `api.openai.com`)، يفعّل OpenClaw تلقائيًا Compaction من جهة الخادم:
- يفرض `store: true` (ما لم يضبط توافق النموذج `supportsStore: false`)
- يفرض `store: true` (ما لم يعيّن توافق النموذج `supportsStore: false`)
- يحقن `context_management: [{ type: "compaction", compact_threshold: ... }]`
- القيمة الافتراضية لـ `compact_threshold`: ‏70% من `contextWindow` (أو `80000` عند عدم توفرها)
- القيمة الافتراضية لـ `compact_threshold`: 70% من `contextWindow` (أو `80000` عند عدم توفرها)
<Tabs>
<Tab title="تفعيل صريح">
يكون هذا مفيدًا لنقاط النهاية المتوافقة مثل Azure OpenAI Responses:
<Tab title="التفعيل صراحةً">
مفيد لنقاط النهاية المتوافقة مثل Azure OpenAI Responses:
```json5
{
@ -572,12 +695,12 @@ x-i18n:
</Tabs>
<Note>
يتحكم `responsesServerCompaction` فقط في حقن `context_management`. أما نماذج OpenAI Responses المباشرة فلا تزال تفرض `store: true` ما لم يضبط التوافق `supportsStore: false`.
يتحكم `responsesServerCompaction` فقط في حقن `context_management`. ولا تزال نماذج OpenAI Responses المباشرة تفرض `store: true` ما لم يعيّن التوافق `supportsStore: false`.
</Note>
</Accordion>
<Accordion title="وضع GPT الصارم الخاص بالوكلاء">
<Accordion title="وضع GPT العامل الصارم">
بالنسبة إلى تشغيلات عائلة GPT-5 على `openai/*` و`openai-codex/*`، يمكن لـ OpenClaw استخدام عقد تنفيذ مضمّن أكثر صرامة:
```json5
@ -591,32 +714,32 @@ x-i18n:
```
مع `strict-agentic`، يقوم OpenClaw بما يلي:
- لم يعد يعامل الدور الذي يحتوي على خطة فقط على أنه تقدم ناجح عندما يكون إجراء أداة متاحًا
- يعيد محاولة الدور مع توجيه "نفّذ الآن"
- يفعّل تلقائيًا `update_plan` للأعمال الكبيرة
- يعرض حالة حظر صريحة إذا استمر النموذج في التخطيط من دون تنفيذ
- لم يعد يعتبر دورًا يحتوي على خطة فقط تقدمًا ناجحًا عندما يكون إجراء أداة متاحًا
- يعيد محاولة الدور مع توجيه للتصرف الآن
- يفعّل `update_plan` تلقائيًا للأعمال الجوهرية
- يعرض حالة تعطّل صريحة إذا استمر النموذج في التخطيط من دون تنفيذ
<Note>
هذا النطاق يقتصر على تشغيلات عائلة GPT-5 الخاصة بـ OpenAI وCodex فقط. أما الموفّرون الآخرون والعائلات الأقدم من النماذج فيحتفظون بالسلوك الافتراضي.
يقتصر ذلك على تشغيلات عائلة GPT-5 الخاصة بـ OpenAI وCodex فقط. أما الموفّرون الآخرون وعائلات النماذج الأقدم فتبقي السلوك الافتراضي.
</Note>
</Accordion>
<Accordion title="المسارات الأصلية مقابل المسارات المتوافقة مع OpenAI">
يتعامل OpenClaw مع نقاط النهاية المباشرة لـ OpenAI وCodex وAzure OpenAI بصورة مختلفة عن proxies العامة المتوافقة مع OpenAI على `/v1`:
يتعامل OpenClaw مع نقاط النهاية المباشرة الخاصة بـ OpenAI وCodex وAzure OpenAI بشكل مختلف عن واجهات proxy العامة المتوافقة مع OpenAI عبر `/v1`:
**المسارات الأصلية** (`openai/*` و`openai-codex/*` وAzure OpenAI):
- تحتفظ بـ `reasoning: { effort: "none" }` فقط للنماذج التي تدعم قيمة OpenAI `none`
- تحذف reasoning المعطل للنماذج أو proxies التي ترفض `reasoning.effort: "none"`
- تجعل مخططات الأدوات في الوضع الصارم افتراضيًا
- ترفق رؤوس attribution مخفية على المضيفين الأصليين المتحقق منهم فقط
- تحتفظ بشكل الطلبات الخاص بـ OpenAI فقط (`service_tier`, `store`, وتوافق reasoning، وتلميحات prompt-cache)
- تُبقي `reasoning: { effort: "none" }` فقط للنماذج التي تدعم قيمة `none` الخاصة بـ OpenAI
- تحذف التعليل المعطّل للنماذج أو الوكلاء proxies الذين يرفضون `reasoning.effort: "none"`
- تجعل مخططات الأدوات افتراضيًا في الوضع الصارم
- ترفق ترويسات إسناد مخفية على المضيفين الأصليين المتحقق منهم فقط
- تُبقي تشكيل الطلبات الخاص بـ OpenAI فقط (`service_tier` و`store` وتوافق reasoning وتلميحات التخزين المؤقت للموجهات)
**المسارات المتوافقة/عبر proxy:**
- تستخدم سلوك توافق أكثر تساهلًا
- لا تفرض مخططات أدوات صارمة أو رؤوسًا أصلية فقط
**مسارات proxy/المسارات المتوافقة:**
- تستخدم سلوك توافق أكثر مرونة
- لا تفرض مخططات أدوات صارمة أو ترويسات أصلية فقط
يستخدم Azure OpenAI النقل الأصلي وسلوك التوافق الأصلي، لكنه لا يتلقى رؤوس attribution المخفية.
تستخدم Azure OpenAI سلوك نقل وتوافق أصليًا لكنها لا تتلقى ترويسات الإسناد المخفية.
</Accordion>
</AccordionGroup>
@ -625,12 +748,12 @@ x-i18n:
<CardGroup cols={2}>
<Card title="اختيار النموذج" href="/ar/concepts/model-providers" icon="layers">
اختيار الموفّرين، ومراجع النماذج، وسلوك failover.
اختيار الموفّرين ومراجع النماذج وسلوك تجاوز الفشل.
</Card>
<Card title="توليد الصور" href="/ar/tools/image-generation" icon="image">
<Card title="إنشاء الصور" href="/ar/tools/image-generation" icon="image">
معلمات أداة الصور المشتركة واختيار الموفّر.
</Card>
<Card title="توليد الفيديو" href="/ar/tools/video-generation" icon="video">
<Card title="إنشاء الفيديو" href="/ar/tools/video-generation" icon="video">
معلمات أداة الفيديو المشتركة واختيار الموفّر.
</Card>
<Card title="OAuth والمصادقة" href="/ar/gateway/authentication" icon="key">

95
docs/ar/reference/test.md
View File

@ -1,50 +1,51 @@
---
read_when:
- تشغيل الاختبارات أو إصلاحها
summary: كيفية تشغيل الاختبارات محليًا (vitest) ومتى تستخدم وضعي force/coverage
summary: كيفية تشغيل الاختبارات محليًا (`vitest`) ومتى تستخدم أوضاع force/coverage
title: الاختبارات
x-i18n:
generated_at: "2026-04-22T04:28:55Z"
generated_at: "2026-04-23T14:02:24Z"
model: gpt-5.4
provider: openai
source_hash: ed665840ef2c7728da8ec923eb3ea2878d9b20a841cb2fe4116a7f6334567b8e
source_hash: e0bcecb0868b3b68361e5ef78afc3170f2a481771bda8f7d54200b1d778d044a
source_path: reference/test.md
workflow: 15
---
# الاختبارات
- مجموعة الاختبارات الكاملة (المجموعات، والاختبارات المباشرة، وDocker): [الاختبار](/ar/help/testing)
- مجموعة الاختبارات الكاملة (المجموعات، والاختبارات الحية، وDocker): [الاختبار](/ar/help/testing)
- `pnpm test:force`: يوقف أي عملية Gateway عالقة تمسك بمنفذ التحكم الافتراضي، ثم يشغّل مجموعة Vitest الكاملة باستخدام منفذ Gateway معزول حتى لا تتعارض اختبارات الخادم مع نسخة قيد التشغيل. استخدم هذا عندما يترك تشغيل سابق لـ Gateway المنفذ 18789 مشغولًا.
- `pnpm test:coverage`: يشغّل مجموعة اختبارات الوحدات مع تغطية V8 (عبر `vitest.unit.config.ts`). هذه بوابة تغطية للوحدات للملفات المحمّلة، وليست تغطية لجميع ملفات المستودع. الحدود هي 70% للأسطر/الدوال/التعليمات و55% للفروع. وبما أن `coverage.all` يساوي false، تقيس البوابة الملفات التي حمّلتها مجموعة تغطية الوحدات بدلًا من اعتبار كل ملف مصدر في المسارات المقسمة غير مغطى.
- `pnpm test:force`: ينهي أي عملية Gateway باقية تحتجز منفذ التحكم الافتراضي، ثم يشغّل مجموعة Vitest الكاملة باستخدام منفذ Gateway معزول حتى لا تتعارض اختبارات الخادم مع نسخة قيد التشغيل. استخدم هذا عندما يترك تشغيل سابق لـ Gateway المنفذ 18789 مشغولًا.
- `pnpm test:coverage`: يشغّل مجموعة اختبارات الوحدات مع تغطية V8 (عبر `vitest.unit.config.ts`). هذه بوابة تغطية لوحدات الملفات المحمّلة، وليست تغطية لكل ملفات المستودع. العتبات هي 70% للأسطر/الدوال/التعابير و55% للفروع. ولأن `coverage.all` تساوي false، فإن البوابة تقيس الملفات التي حمّلتها مجموعة تغطية الوحدات بدلًا من اعتبار كل ملف مصدر في المسارات المقسمة غير مغطى.
- `pnpm test:coverage:changed`: يشغّل تغطية الوحدات فقط للملفات التي تغيّرت منذ `origin/main`.
- `pnpm test:changed`: يوسّع مسارات git المتغيرة إلى مسارات Vitest محددة النطاق عندما يقتصر الفرق على ملفات المصدر/الاختبار القابلة للتوجيه. وتظل تغييرات الإعداد/التهيئة تعود إلى تشغيل المشاريع الجذرية الأصلية بحيث تُعاد تشغيل تعديلات الربط بشكل واسع عند الحاجة.
- `pnpm changed:lanes`: يعرض المسارات المعمارية التي يفعّلها الفرق مقابل `origin/main`.
- `pnpm check:changed`: يشغّل بوابة التغييرات الذكية للفرق مقابل `origin/main`. وهو يشغّل عمل النواة مع مسارات اختبارات النواة، وعمل الامتدادات مع مسارات اختبارات الامتدادات، والعمل الخاص بالاختبارات فقط مع typecheck/الاختبارات فقط، ويوسّع تغييرات Plugin SDK العامة أو عقود plugin إلى تحقق الامتدادات، ويحافظ على زيادات الإصدارات الخاصة ببيانات الإصدار فقط ضمن فحوصات موجّهة للإصدار/التكوين/اعتماديات الجذر.
- `pnpm test`: يوجّه أهداف الملفات/الأدلة الصريحة عبر مسارات Vitest محددة النطاق. أما التشغيلات غير المستهدفة فتستخدم مجموعات shards ثابتة وتتوسع إلى إعدادات نهائية للتنفيذ المحلي المتوازي؛ وتُوسّع مجموعة الامتدادات دائمًا إلى إعدادات shards لكل امتداد بدلًا من عملية مشروع جذري عملاقة واحدة.
- تقوم تشغيلات shards الكاملة وامتداداتها بتحديث بيانات التوقيت المحلية في `.artifacts/vitest-shard-timings.json`؛ وتستخدم التشغيلات اللاحقة هذه التوقيتات لموازنة shards البطيئة والسريعة. عيّن `OPENCLAW_TEST_PROJECTS_TIMINGS=0` لتجاهل عنصر التوقيت المحلي.
- يتم الآن توجيه ملفات اختبار `plugin-sdk` و`commands` المحددة عبر مسارات خفيفة مخصصة تُبقي فقط `test/setup.ts`، بينما تبقى الحالات الثقيلة وقت التشغيل في مساراتها الحالية.
- كما تُطابق ملفات المصدر المساعدة المحددة في `plugin-sdk` و`commands` الأمر `pnpm test:changed` مع اختبارات شقيقة صريحة في تلك المسارات الخفيفة، بحيث تتجنب التعديلات الصغيرة على المساعدات إعادة تشغيل المجموعات الثقيلة المدعومة بوقت التشغيل.
- ينقسم `auto-reply` الآن أيضًا إلى ثلاثة إعدادات مخصصة (`core` و`top-level` و`reply`) حتى لا تهيمن عدة الرد على اختبارات الحالة/الرموز/المساعدات الأخف في المستوى الأعلى.
- `pnpm test:changed`: يوسّع مسارات git المتغيرة إلى مسارات Vitest محددة النطاق عندما يقتصر الفرق على ملفات المصدر/الاختبار القابلة للتوجيه. أما تغييرات الإعداد/التهيئة فتعود إلى تشغيل المشاريع الجذرية الأصلي حتى تعيد تعديلات التوصيل التشغيل على نطاق واسع عند الحاجة.
- `pnpm changed:lanes`: يعرض المسارات المعمارية التي يُشغّلها الفرق مقارنةً بـ `origin/main`.
- `pnpm check:changed`: يشغّل بوابة التغييرات الذكية للفرق مقارنةً بـ `origin/main`. فهو يشغّل أعمال النواة مع مسارات اختبارات النواة، وأعمال الإضافات مع مسارات اختبارات الإضافات، والأعمال الخاصة بالاختبارات فقط مع فحص أنواع الاختبار/الاختبارات فقط، ويوسّع تغييرات Plugin SDK العامة أو `plugin-contract` إلى التحقق من الإضافات، ويبقي زيادات الإصدارات الخاصة ببيانات الإصدار فقط على فحوصات مستهدفة للإصدار/الإعداد/تبعيات الجذر.
- `pnpm test`: يوجّه أهداف الملفات/الأدلة الصريحة عبر مسارات Vitest محددة النطاق. أما التشغيلات غير المستهدفة فتستخدم مجموعات shards ثابتة وتتوسع إلى إعدادات فرعية للتنفيذ المحلي المتوازي؛ وتتمدد مجموعة الإضافات دائمًا إلى إعدادات shards لكل إضافة بدلًا من عملية مشروع جذري واحدة ضخمة.
- تقوم تشغيلات المجموعة الكاملة ومجموعات shards الخاصة بالإضافات بتحديث بيانات التوقيت المحلية في `.artifacts/vitest-shard-timings.json`؛ وتستخدم التشغيلات اللاحقة تلك التوقيتات لموازنة الـ shards البطيئة والسريعة. اضبط `OPENCLAW_TEST_PROJECTS_TIMINGS=0` لتجاهل ملف التوقيت المحلي.
- تُوجَّه بعض ملفات اختبار `plugin-sdk` و`commands` المحددة الآن عبر مسارات خفيفة مخصصة تُبقي فقط على `test/setup.ts`، مع إبقاء الحالات الثقيلة من حيث وقت التشغيل على مساراتها الحالية.
- كما تربط بعض ملفات المصدر المساعدة المحددة في `plugin-sdk` و`commands` أمر `pnpm test:changed` باختبارات صريحة مجاورة في تلك المسارات الخفيفة، بحيث تتجنب التعديلات الصغيرة في المساعدات إعادة تشغيل المجموعات الثقيلة المدعومة بوقت التشغيل.
- ينقسم `auto-reply` الآن أيضًا إلى ثلاثة إعدادات مخصصة (`core` و`top-level` و`reply`) حتى لا يهيمن harness الخاص بالرد على اختبارات الحالة/الرمز/المساعد الأخف في المستوى الأعلى.
- يستخدم إعداد Vitest الأساسي الآن افتراضيًا `pool: "threads"` و`isolate: false`، مع تمكين المشغّل المشترك غير المعزول عبر إعدادات المستودع.
- يشغّل `pnpm test:channels` الملف `vitest.channels.config.ts`.
- يشغّل `pnpm test:extensions` و`pnpm test extensions` جميع shards الخاصة بالامتدادات/plugins. وتعمل امتدادات القنوات الثقيلة وOpenAI كـ shards مخصصة؛ بينما تبقى مجموعات الامتدادات الأخرى مجمّعة. استخدم `pnpm test extensions/<id>` لمسار plugin مضمّن واحد.
- `pnpm test:perf:imports`: يفعّل تقارير مدة الاستيراد + تفصيلات الاستيراد في Vitest، مع الاستمرار في استخدام التوجيه المحدد النطاق لأهداف الملفات/الأدلة الصريحة.
- `pnpm test:perf:imports:changed`: التنميط نفسه للاستيراد، ولكن فقط للملفات التي تغيّرت منذ `origin/main`.
- `pnpm test:perf:changed:bench -- --ref <git-ref>` يقيس أداء المسار الموجّه لوضع changed مقابل تشغيل المشروع الجذري الأصلي لنفس فرق git المُلتزم.
- `pnpm test:perf:changed:bench -- --worktree` يقيس أداء مجموعة تغييرات worktree الحالية دون الالتزام أولًا.
- `pnpm test:perf:profile:main`: يكتب ملف تعريف CPU لخيط Vitest الرئيسي (`.artifacts/vitest-main-profile`).
- يشغّل `pnpm test:extensions` و`pnpm test extensions` جميع shards الإضافات/Plugins. تعمل إضافات القنوات الثقيلة وOpenAI كـ shards مخصصة؛ بينما تبقى مجموعات الإضافات الأخرى مجمعة. استخدم `pnpm test extensions/<id>` لمسار Plugin مجمّع واحد.
- `pnpm test:perf:imports`: يفعّل تقارير مدة الاستيراد + تفصيلات الاستيراد في Vitest، مع الاستمرار في استخدام توجيه المسارات المحددة النطاق لأهداف الملفات/الأدلة الصريحة.
- `pnpm test:perf:imports:changed`: نفس تحليل الاستيراد، لكن فقط للملفات التي تغيّرت منذ `origin/main`.
- `pnpm test:perf:changed:bench -- --ref <git-ref>` يقيس أداء مسار التغييرات الموجّه مقابل تشغيل المشاريع الجذرية الأصلي لنفس فرق git المُلتزم.
- `pnpm test:perf:changed:bench -- --worktree` يقيس أداء مجموعة تغييرات شجرة العمل الحالية دون الالتزام أولًا.
- `pnpm test:perf:profile:main`: يكتب ملف تعريف CPU للخيط الرئيسي في Vitest (`.artifacts/vitest-main-profile`).
- `pnpm test:perf:profile:runner`: يكتب ملفات تعريف CPU + heap لمشغّل الوحدات (`.artifacts/vitest-runner-profile`).
- تكامل Gateway: اشتراك اختياري عبر `OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test` أو `pnpm test:gateway`.
- `pnpm test:e2e`: يشغّل اختبارات smoke شاملة لـ Gateway (إقران WS/HTTP/Node متعدد النسخ). يستخدم افتراضيًا `threads` + `isolate: false` مع عمّال متكيّفين في `vitest.e2e.config.ts`؛ اضبطه باستخدام `OPENCLAW_E2E_WORKERS=<n>` وعيّن `OPENCLAW_E2E_VERBOSE=1` للحصول على سجلات مفصلة.
- `pnpm test:live`: يشغّل اختبارات المزوّدات المباشرة (minimax/zai). يتطلب مفاتيح API و`LIVE=1` (أو `*_LIVE_TEST=1` الخاص بالمزوّد) لإلغاء التخطي.
- `pnpm test:docker:openwebui`: يبدأ OpenClaw + Open WebUI ضمن Docker، ويسجل الدخول عبر Open WebUI، ويتحقق من `/api/models`، ثم يشغّل دردشة حقيقية عبر proxy من خلال `/api/chat/completions`. ويتطلب مفتاح نموذج مباشر صالحًا (مثل OpenAI في `~/.profile`)، ويسحب صورة Open WebUI خارجية، ولا يُتوقع أن يكون مستقرًا في CI مثل مجموعات الوحدات/e2e العادية.
- `pnpm test:docker:mcp-channels`: يبدأ حاوية Gateway مزروعة وحاوية عميل ثانية تشغّل `openclaw mcp serve`، ثم يتحقق من اكتشاف المحادثات الموجّهة، وقراءات transcript، وبيانات attachment الوصفية، وسلوك طابور الأحداث المباشرة، وتوجيه الإرسال الصادر، وإشعارات القنوات + الأذونات بأسلوب Claude عبر جسر stdio الحقيقي. وتقرأ مطالبة إشعار Claude إطارات MCP الخام من stdio مباشرة حتى يعكس اختبار smoke ما يصدره الجسر فعلًا.
- تكامل Gateway: تفعيل اختياري عبر `OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test` أو `pnpm test:gateway`.
- `pnpm test:e2e`: يشغّل اختبارات smoke الشاملة لـ Gateway (إقران WS/HTTP/node متعدد النسخ). ويستخدم افتراضيًا `threads` + `isolate: false` مع عمّال متكيفين في `vitest.e2e.config.ts`؛ ويمكنك الضبط عبر `OPENCLAW_E2E_WORKERS=<n>` وتعيين `OPENCLAW_E2E_VERBOSE=1` للحصول على سجلات مفصلة.
- `pnpm test:live`: يشغّل اختبارات المزودات الحية (minimax/zai). ويتطلب مفاتيح API و`LIVE=1` (أو `*_LIVE_TEST=1` الخاصة بالمزوّد) لإلغاء التخطي.
- `pnpm test:docker:all`: يبني صورة الاختبار الحي المشتركة وصورة Docker E2E مرة واحدة، ثم يشغّل مسارات Docker smoke مع `OPENCLAW_SKIP_DOCKER_BUILD=1` وبدرجة توازٍ افتراضية قدرها 4. اضبطها عبر `OPENCLAW_DOCKER_ALL_PARALLELISM=<n>`. ويوقف المشغّل جدولة مسارات جديدة في المجموعة بعد أول فشل ما لم يُضبط `OPENCLAW_DOCKER_ALL_FAIL_FAST=0`، ولكل مسار مهلة 120 دقيقة يمكن تجاوزها باستخدام `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`. تعمل المسارات الحساسة لبدء التشغيل أو المزوّد بشكل حصري بعد المجموعة المتوازية. وتُكتب سجلات كل مسار تحت `.artifacts/docker-tests/<run-id>/`.
- `pnpm test:docker:openwebui`: يبدأ OpenClaw + Open WebUI ضمن Docker، ويسجّل الدخول عبر Open WebUI، ويفحص `/api/models`، ثم يشغّل دردشة حقيقية عبر الوكيل من خلال `/api/chat/completions`. ويتطلب مفتاح نموذج حي صالحًا (مثل OpenAI في `~/.profile`)، ويسحب صورة Open WebUI خارجية، ولا يُتوقع أن يكون مستقرًا في CI مثل مجموعات الوحدات/e2e العادية.
- `pnpm test:docker:mcp-channels`: يبدأ حاوية Gateway مهيأة مسبقًا وحاوية عميل ثانية تشغّل `openclaw mcp serve`، ثم يتحقق من اكتشاف المحادثة الموجّهة، وقراءات النصوص، وmetadata الخاصة بالمرفقات، وسلوك طابور الأحداث الحية، وتوجيه الإرسال الصادر، وإشعارات القنوات + الأذونات بأسلوب Claude عبر جسر stdio الحقيقي. ويقرأ تأكيد إشعارات Claude إطارات stdio MCP الخام مباشرةً حتى يعكس smoke ما يصدره الجسر فعليًا.
## بوابة PR المحلية
لفحوصات البوابة/الإرسال المحلية لـ PR، شغّل:
لفحوصات البوابة/الهبوط المحلية الخاصة بـ PR، شغّل:
- `pnpm check:changed`
- `pnpm check`
@ -53,29 +54,29 @@ x-i18n:
- `pnpm test`
- `pnpm check:docs`
إذا كان `pnpm test` غير مستقر على مضيف مثقل، فأعد تشغيله مرة واحدة قبل اعتباره تراجعًا، ثم اعزله باستخدام `pnpm test <path/to/test>`. وبالنسبة إلى المضيفات المقيّدة الذاكرة، استخدم:
إذا أصبح `pnpm test` غير مستقر على مضيف مثقل، فأعد تشغيله مرة واحدة قبل اعتباره تراجعًا، ثم اعزل الحالة باستخدام `pnpm test <path/to/test>`. وبالنسبة للمضيفات ذات الذاكرة المحدودة، استخدم:
- `OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test`
- `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/tmp/openclaw-vitest-cache pnpm test:changed`
## قياس زمن استجابة النموذج (مفاتيح محلية)
## قياس زمن وصول النموذج (مفاتيح محلية)
السكربت: [`scripts/bench-model.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/bench-model.ts)
البرنامج النصي: [`scripts/bench-model.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/bench-model.ts)
الاستخدام:
- `source ~/.profile && pnpm tsx scripts/bench-model.ts --runs 10`
- متغيرات بيئة اختيارية: `MINIMAX_API_KEY` و`MINIMAX_BASE_URL` و`MINIMAX_MODEL` و`ANTHROPIC_API_KEY`
- prompt الافتراضي: “Reply with a single word: ok. No punctuation or extra text.”
- الـ prompt الافتراضي: “Reply with a single word: ok. No punctuation or extra text.”
آخر تشغيل (2025-12-31، 20 تشغيلًا):
- median لـ minimax: ‏1279ms (الحد الأدنى 1114، الحد الأقصى 2431)
- median لـ opus: ‏2454ms (الحد الأدنى 1224، الحد الأقصى 3170)
- الوسيط في minimax هو 1279ms (الحد الأدنى 1114، الحد الأقصى 2431)
- الوسيط في opus هو 2454ms (الحد الأدنى 1224، الحد الأقصى 3170)
## قياس بدء تشغيل CLI
السكربت: [`scripts/bench-cli-startup.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/bench-cli-startup.ts)
البرنامج النصي: [`scripts/bench-cli-startup.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/bench-cli-startup.ts)
الاستخدام:
@ -96,39 +97,39 @@ x-i18n:
الإعدادات المسبقة:
- `startup`: ‏`--version`، و`--help`، و`health`، و`health --json`، و`status --json`، و`status`
- `real`: ‏`health`، و`status`، و`status --json`، و`sessions`، و`sessions --json`، و`agents list --json`، و`gateway status`، و`gateway status --json`، و`gateway health --json`، و`config get gateway.port`
- `startup`: ‏`--version` و`--help` و`health` و`health --json` و`status --json` و`status`
- `real`: ‏`health` و`status` و`status --json` و`sessions` و`sessions --json` و`agents list --json` و`gateway status` و`gateway status --json` و`gateway health --json` و`config get gateway.port`
- `all`: كلا الإعدادين المسبقين
يتضمن الإخراج `sampleCount`، وavg، وp50، وp95، والحدين الأدنى/الأقصى، وتوزيع exit-code/signal، وملخصات RSS القصوى لكل أمر. وتكتب الخيارات `--cpu-prof-dir` / `--heap-prof-dir` ملفات تعريف V8 لكل تشغيل بحيث يستخدم التقاط التوقيت وملفات التعريف الأداة نفسها.
يتضمن الإخراج `sampleCount`، والمتوسط، وp50، وp95، والحد الأدنى/الأقصى، وتوزيع exit-code/signal، وملخصات أقصى RSS لكل أمر. ويكتب الخياران `--cpu-prof-dir` / `--heap-prof-dir` ملفات تعريف V8 لكل تشغيل بحيث يستخدم القياس والتقاط ملفات التعريف harness نفسه.
اصطلاحات الإخراج المحفوظ:
اتفاقيات الإخراج المحفوظ:
- يكتب `pnpm test:startup:bench:smoke` عنصر smoke الموجّه في `.artifacts/cli-startup-bench-smoke.json`
- يكتب `pnpm test:startup:bench:save` عنصر المجموعة الكاملة في `.artifacts/cli-startup-bench-all.json` باستخدام `runs=5` و`warmup=1`
- يحدّث `pnpm test:startup:bench:update` ملف baseline المثبّت في المستودع عند `test/fixtures/cli-startup-bench.json` باستخدام `runs=5` و`warmup=1`
- يكتب `pnpm test:startup:bench:smoke` ناتج smoke المستهدف في `.artifacts/cli-startup-bench-smoke.json`
- يكتب `pnpm test:startup:bench:save` ناتج المجموعة الكاملة في `.artifacts/cli-startup-bench-all.json` باستخدام `runs=5` و`warmup=1`
- يحدّث `pnpm test:startup:bench:update` ملف baseline المثبت في `test/fixtures/cli-startup-bench.json` باستخدام `runs=5` و`warmup=1`
الملف المثبّت في المستودع:
الملف المثبت في المستودع:
- `test/fixtures/cli-startup-bench.json`
- حدّثه باستخدام `pnpm test:startup:bench:update`
- قارن النتائج الحالية بالملف باستخدام `pnpm test:startup:bench:check`
## Onboarding E2E (Docker)
## Onboarding E2E ‏(Docker)
يُعد Docker اختياريًا؛ وهذا مطلوب فقط لاختبارات smoke الخاصة بالإعداد الأولي ضمن الحاويات.
يُعد Docker اختياريًا؛ وهذا مطلوب فقط لاختبارات smoke الخاصة بالتهيئة الأولى ضمن الحاويات.
التدفق الكامل لبدء التشغيل البارد في حاوية Linux نظيفة:
تدفق بدء تشغيل كامل من الصفر داخل حاوية Linux نظيفة:
```bash
scripts/e2e/onboard-docker.sh
```
يقود هذا السكربت المعالج التفاعلي عبر pseudo-tty، ويتحقق من ملفات config/workspace/session، ثم يبدأ Gateway ويشغّل `openclaw health`.
يقود هذا البرنامج النصي المعالج التفاعلي عبر pseudo-tty، ويتحقق من ملفات config/workspace/session، ثم يبدأ Gateway ويشغّل `openclaw health`.
## اختبار smoke لاستيراد QR (Docker)
## smoke لاستيراد QR ‏(Docker)
يضمن تحميل `qrcode-terminal` ضمن بيئات Node المدعومة في Docker (Node 24 افتراضيًا، وNode 22 متوافق):
يضمن أن `qrcode-terminal` يُحمَّل ضمن بيئات Node المدعومة في Docker (الافتراضي Node 24، والمتوافق Node 22):
```bash
pnpm test:docker:qr

189
docs/ar/tools/image-generation.md
View File

@ -1,31 +1,31 @@
---
read_when:
- إنشاء الصور عبر الوكيل
- تهيئة مزوّدي ونماذج توليد الصور
- تكوين موفري خدمة إنشاء الصور والنماذج
- فهم معاملات أداة `image_generate`
summary: إنشاء الصور وتحريرها باستخدام المزوّدين المهيئين (OpenAI وGoogle Gemini وfal وMiniMax وComfyUI وVydra وxAI)
title: توليد الصور
summary: إنشاء الصور وتحريرها باستخدام موفري الخدمة المضبوطين (OpenAI وGoogle Gemini وfal وMiniMax وComfyUI وVydra وxAI)
title: إنشاء الصور
x-i18n:
generated_at: "2026-04-23T07:33:38Z"
generated_at: "2026-04-23T14:02:52Z"
model: gpt-5.4
provider: openai
source_hash: 228049c74dd3437544cda6418da665aed375c0494ef36a6927d15c28d7783bbd
source_hash: 0fbd8eda2cb0867d1426b9349f6778c231051d600ebe451534efbee0e215c871
source_path: tools/image-generation.md
workflow: 15
---
# توليد الصور
# إنشاء الصور
تتيح أداة `image_generate` للوكيل إنشاء الصور وتحريرها باستخدام المزوّدات المهيأة لديك. وتُسلَّم الصور المُولَّدة تلقائيًا كمرفقات وسائط في رد الوكيل.
تتيح أداة `image_generate` للوكيل إنشاء الصور وتحريرها باستخدام موفري الخدمة المضبوطين لديك. وتُسلَّم الصور المُنشأة تلقائيًا كمرفقات وسائط في رد الوكيل.
<Note>
لا تظهر الأداة إلا عندما يكون مزوّد واحد على الأقل لتوليد الصور متاحًا. إذا كنت لا ترى `image_generate` ضمن أدوات وكيلك، فقم بتهيئة `agents.defaults.imageGenerationModel` أو اضبط مفتاح API لمزوّد.
لا تظهر الأداة إلا عندما يكون موفر خدمة واحد على الأقل لإنشاء الصور متاحًا. إذا لم ترَ `image_generate` ضمن أدوات وكيلك، فاضبط `agents.defaults.imageGenerationModel` أو أعد إعداد مفتاح API لموفر خدمة.
</Note>
## بداية سريعة
## البدء السريع
1. اضبط مفتاح API لمزوّد واحد على الأقل (مثل `OPENAI_API_KEY` أو `GEMINI_API_KEY`).
2. اضبط اختياريًا النموذج المفضل لديك:
1. اضبط مفتاح API لموفر خدمة واحد على الأقل (مثل `OPENAI_API_KEY` أو `GEMINI_API_KEY`).
2. اختياريًا، اضبط النموذج المفضل لديك:
```json5
{
@ -39,23 +39,23 @@ x-i18n:
}
```
3. اطلب من الوكيل: _"Generate an image of a friendly lobster mascot."_
3. اطلب من الوكيل: _"أنشئ صورة لتميمة كركند ودودة."_
يستدعي الوكيل `image_generate` تلقائيًا. ولا حاجة إلى قائمة سماح للأداة — فهي مفعّلة افتراضيًا عندما يكون مزوّد متاحًا.
سيستدعي الوكيل `image_generate` تلقائيًا. لا حاجة إلى قائمة سماح للأدوات — فهي مفعلة افتراضيًا عندما يكون موفر خدمة متاحًا.
## المزوّدات المدعومة
## موفرو الخدمة المدعومون
| المزوّد | النموذج الافتراضي | دعم التحرير | مفتاح API |
| -------- | -------------------------------- | ---------------------------------- | ----------------------------------------------------- |
| OpenAI | `gpt-image-2` | نعم (حتى 5 صور) | `OPENAI_API_KEY` |
| Google | `gemini-3.1-flash-image-preview` | نعم | `GEMINI_API_KEY` أو `GOOGLE_API_KEY` |
| fal | `fal-ai/flux/dev` | نعم | `FAL_KEY` |
| MiniMax | `image-01` | نعم (مرجع للموضوع) | `MINIMAX_API_KEY` أو MiniMax OAuth (`minimax-portal`) |
| ComfyUI | `workflow` | نعم (صورة واحدة، وفق workflow) | `COMFY_API_KEY` أو `COMFY_CLOUD_API_KEY` للسحابة |
| Vydra | `grok-imagine` | لا | `VYDRA_API_KEY` |
| xAI | `grok-imagine-image` | نعم (حتى 5 صور) | `XAI_API_KEY` |
| Provider | النموذج الافتراضي | دعم التحرير | مفتاح API |
| -------- | ------------------------------ | ---------------------------------- | ------------------------------------------------------ |
| OpenAI | `gpt-image-2` | نعم (حتى 5 صور) | `OPENAI_API_KEY` |
| Google | `gemini-3.1-flash-image-preview` | نعم | `GEMINI_API_KEY` أو `GOOGLE_API_KEY` |
| fal | `fal-ai/flux/dev` | نعم | `FAL_KEY` |
| MiniMax | `image-01` | نعم (مرجع موضوع) | `MINIMAX_API_KEY` أو MiniMax OAuth (`minimax-portal`) |
| ComfyUI | `workflow` | نعم (صورة واحدة، وفق سير العمل) | `COMFY_API_KEY` أو `COMFY_CLOUD_API_KEY` للسحابة |
| Vydra | `grok-imagine` | لا | `VYDRA_API_KEY` |
| xAI | `grok-imagine-image` | نعم (حتى 5 صور) | `XAI_API_KEY` |
استخدم `action: "list"` لفحص المزوّدات والنماذج المتاحة وقت التشغيل:
استخدم `action: "list"` لفحص موفري الخدمة والنماذج المتاحة وقت التشغيل:
```
/tool image_generate action=list
@ -63,24 +63,24 @@ x-i18n:
## معاملات الأداة
| المعامل | النوع | الوصف |
| ------------- | -------- | ------------------------------------------------------------------------------------- |
| `prompt` | string | prompt لتوليد الصورة (مطلوب لـ `action: "generate"`) |
| `action` | string | `"generate"` (الافتراضي) أو `"list"` لفحص المزوّدات |
| `model` | string | تجاوز للمزوّد/النموذج، مثل `openai/gpt-image-2` |
| `image` | string | مسار صورة مرجعية واحدة أو عنوان URL لوضع التحرير |
| `images` | string[] | عدة صور مرجعية لوضع التحرير (حتى 5) |
| `size` | string | تلميح الحجم: `1024x1024` أو `1536x1024` أو `1024x1536` أو `2048x2048` أو `3840x2160` |
| `aspectRatio` | string | نسبة العرض إلى الارتفاع: `1:1` أو `2:3` أو `3:2` أو `3:4` أو `4:3` أو `4:5` أو `5:4` أو `9:16` أو `16:9` أو `21:9` |
| `resolution` | string | تلميح الدقة: `1K` أو `2K` أو `4K` |
| `count` | number | عدد الصور المطلوب توليدها (1–4) |
| `filename` | string | تلميح اسم ملف الإخراج |
| المعامل | النوع | الوصف |
| ------------ | -------- | --------------------------------------------------------------------------------------- |
| `prompt` | string | مطالبة إنشاء الصورة (مطلوبة لـ `action: "generate"`) |
| `action` | string | `"generate"` (افتراضي) أو `"list"` لفحص موفري الخدمة |
| `model` | string | تجاوز Provider/نموذج، مثل `openai/gpt-image-2` |
| `image` | string | مسار صورة مرجعية واحدة أو URL لوضع التحرير |
| `images` | string[] | صور مرجعية متعددة لوضع التحرير (حتى 5) |
| `size` | string | تلميح الحجم: `1024x1024`، `1536x1024`، `1024x1536`، `2048x2048`، `3840x2160` |
| `aspectRatio`| string | نسبة الأبعاد: `1:1`، `2:3`، `3:2`، `3:4`، `4:3`، `4:5`، `5:4`، `9:16`، `16:9`، `21:9` |
| `resolution` | string | تلميح الدقة: `1K` أو `2K` أو `4K` |
| `count` | number | عدد الصور المطلوب إنشاؤها (1–4) |
| `filename` | string | تلميح اسم ملف الإخراج |
لا تدعم كل المزوّدات جميع المعاملات. وعندما يدعم مزود fallback خيار هندسة قريبًا بدلًا من الخيار المطلوب تمامًا، يقوم OpenClaw بإعادة التعيين إلى أقرب حجم أو نسبة عرض إلى ارتفاع أو دقة مدعومة قبل الإرسال. أما التجاوزات غير المدعومة فعليًا فسيتم الإبلاغ عنها في نتيجة الأداة.
لا تدعم كل موفري الخدمة جميع المعاملات. وعندما يدعم موفر خدمة احتياطي خيارًا هندسيًا قريبًا بدلًا من الخيار المطلوب بدقة، يعيد OpenClaw تعيينه إلى أقرب حجم أو نسبة أبعاد أو دقة مدعومة قبل الإرسال. أما التجاوزات غير المدعومة فعلًا فما تزال تُبلّغ في نتيجة الأداة.
تُبلّغ نتائج الأداة عن الإعدادات المطبقة. وعندما يعيد OpenClaw تعيين الهندسة أثناء fallback للمزوّد، فإن القيم المعادة في `size` و`aspectRatio` و`resolution` تعكس ما تم إرساله فعليًا، بينما تلتقط `details.normalization` ترجمة المطلوب إلى المطبق.
تُبلّغ نتائج الأداة عن الإعدادات المطبقة. وعندما يعيد OpenClaw تعيين الهندسة أثناء الرجوع الاحتياطي بين موفري الخدمة، فإن القيم المعادة في `size` و`aspectRatio` و`resolution` تعكس ما أُرسل فعليًا، ويلتقط `details.normalization` التحويل من المطلوب إلى المطبق.
## التهيئة
## التكوين
### اختيار النموذج
@ -97,114 +97,119 @@ x-i18n:
}
```
### ترتيب اختيار المزوّد
### ترتيب اختيار Provider
عند توليد صورة، يجرب OpenClaw المزوّدات بهذا الترتيب:
عند إنشاء صورة، يجرب OpenClaw موفري الخدمة بهذا الترتيب:
1. **معامل `model`** من استدعاء الأداة (إذا حدده الوكيل)
2. **`imageGenerationModel.primary`** من التهيئة
1. **المعامل `model`** من استدعاء الأداة (إذا حدده الوكيل)
2. **`imageGenerationModel.primary`** من التكوين
3. **`imageGenerationModel.fallbacks`** بالترتيب
4. **الاكتشاف التلقائي** — يستخدم فقط القيم الافتراضية للمزوّدات المدعومة بالمصادقة:
- المزوّد الافتراضي الحالي أولًا
- ثم بقية مزوّدي توليد الصور المسجلين حسب ترتيب معرّف المزوّد
4. **الاكتشاف التلقائي** — يستخدم فقط الإعدادات الافتراضية لموفري الخدمة المدعومة بالمصادقة:
- موفر الخدمة الافتراضي الحالي أولًا
- بقية موفري خدمة إنشاء الصور المسجلين بترتيب معرّف Provider
إذا فشل مزوّد ما (خطأ مصادقة، أو حد معدل، وما إلى ذلك)، تتم تجربة المرشح التالي تلقائيًا. وإذا فشل الجميع، يتضمن الخطأ تفاصيل من كل محاولة.
إذا فشل موفر خدمة (خطأ مصادقة، حد معدل، إلخ)، تُجرَّب المرشحة التالية تلقائيًا. وإذا فشل الجميع، يتضمن الخطأ تفاصيل من كل محاولة.
ملاحظات:
- يكون الاكتشاف التلقائي واعيًا بالمصادقة. لا يدخل افتراضي المزوّد إلى قائمة المرشحين
إلا عندما يتمكن OpenClaw فعليًا من مصادقة ذلك المزوّد.
- الاكتشاف التلقائي واعٍ بالمصادقة. لا يدخل افتراضي موفر الخدمة إلى قائمة المرشحين
إلا عندما يتمكن OpenClaw فعلًا من مصادقة ذلك Provider.
- يكون الاكتشاف التلقائي مفعّلًا افتراضيًا. اضبط
`agents.defaults.mediaGenerationAutoProviderFallback: false` إذا كنت تريد أن يستخدم
توليد الصور فقط الإدخالات الصريحة `model` و`primary` و`fallbacks`.
- استخدم `action: "list"` لفحص المزوّدات المسجلة حاليًا،
ونماذجها الافتراضية، وتلميحات متغيرات env الخاصة بالمصادقة.
إنشاء الصور فقط الإدخالات الصريحة `model` و`primary` و`fallbacks`.
- استخدم `action: "list"` لفحص موفري الخدمة المسجلين حاليًا، والنماذج الافتراضية
الخاصة بهم، وتلميحات متغيرات البيئة الخاصة بالمصادقة.
### تحرير الصور
يدعم OpenAI وGoogle وfal وMiniMax وComfyUI وxAI تحرير الصور المرجعية. مرّر مسار صورة مرجعية أو عنوان URL:
تدعم OpenAI وGoogle وfal وMiniMax وComfyUI وxAI تحرير الصور المرجعية. مرّر مسار صورة مرجعية أو URL:
```
"Generate a watercolor version of this photo" + image: "/path/to/photo.jpg"
"أنشئ نسخة مائية من هذه الصورة" + image: "/path/to/photo.jpg"
```
يدعم OpenAI وGoogle وxAI حتى 5 صور مرجعية عبر المعامل `images`. أما fal وMiniMax وComfyUI فتدعم صورة واحدة.
تدعم OpenAI وGoogle وxAI ما يصل إلى 5 صور مرجعية عبر المعامل `images`. بينما يدعم fal وMiniMax وComfyUI صورة واحدة.
### OpenAI `gpt-image-2`
يفترض توليد الصور في OpenAI افتراضيًا النموذج `openai/gpt-image-2`. ولا يزال
من الممكن اختيار النموذج الأقدم `openai/gpt-image-1` صراحةً، لكن طلبات OpenAI
الجديدة الخاصة بتوليد الصور وتحريرها يجب أن تستخدم `gpt-image-2`.
يستخدم إنشاء الصور في OpenAI النموذج الافتراضي `openai/gpt-image-2`. لا يزال
من الممكن اختيار النموذج الأقدم `openai/gpt-image-1` صراحةً، لكن يجب أن تستخدم
طلبات OpenAI الجديدة لإنشاء الصور وتحريرها `gpt-image-2`.
يدعم `gpt-image-2` كلاً من توليد الصور من النص وتحرير الصور المرجعية
عبر أداة `image_generate` نفسها. يمرر OpenClaw القيم `prompt` و`count` و`size` والصور المرجعية إلى OpenAI. ولا تتلقى OpenAI
القيم `aspectRatio` أو `resolution` مباشرة؛ وعندما يكون ذلك ممكنًا يقوم OpenClaw بتحويلها إلى
`size` مدعوم، وإلا تُبلّغ الأداة عنها على أنها تجاوزات تم تجاهلها.
يدعم `gpt-image-2` كلاً من إنشاء الصور من النص وتحرير الصور المرجعية
عبر أداة `image_generate` نفسها. يمرر OpenClaw القيم `prompt`،
و`count`، و`size`، والصور المرجعية إلى OpenAI. ولا تتلقى OpenAI
القيم `aspectRatio` أو `resolution` مباشرةً؛ وعندما يكون ذلك ممكنًا يعيد OpenClaw
تعيينها إلى `size` مدعومة، وإلا تُبلغ الأداة عنها كتجاوزات تم تجاهلها.
توليد صورة landscape واحدة بدقة 4K:
أنشئ صورة أفقية واحدة بدقة 4K:
```
/tool image_generate action=generate model=openai/gpt-image-2 prompt="A clean editorial poster for OpenClaw image generation" size=3840x2160 count=1
```
توليد صورتين مربعتين:
أنشئ صورتين مربعتين:
```
/tool image_generate action=generate model=openai/gpt-image-2 prompt="Two visual directions for a calm productivity app icon" size=1024x1024 count=2
```
تحرير صورة مرجعية محلية واحدة:
حرّر صورة مرجعية محلية واحدة:
```
/tool image_generate action=generate model=openai/gpt-image-2 prompt="Keep the subject, replace the background with a bright studio setup" image=/path/to/reference.png size=1024x1536
```
التحرير باستخدام عدة مراجع:
حرّر باستخدام مراجع متعددة:
```
/tool image_generate action=generate model=openai/gpt-image-2 prompt="Combine the character identity from the first image with the color palette from the second" images='["/path/to/character.png","/path/to/palette.jpg"]' size=1536x1024
```
يتوفر توليد الصور في MiniMax عبر مساري مصادقة MiniMax المضمّنين معًا:
لتوجيه إنشاء الصور في OpenAI عبر نشر Azure OpenAI بدلًا من
`api.openai.com`، راجع [Azure OpenAI endpoints](/ar/providers/openai#azure-openai-endpoints)
في وثائق OpenAI Provider.
- `minimax/image-01` لإعدادات API-key
يتوفر إنشاء الصور في MiniMax عبر مساري مصادقة MiniMax المضمنين كليهما:
- `minimax/image-01` لإعدادات مفتاح API
- `minimax-portal/image-01` لإعدادات OAuth
## قدرات المزوّد
## قدرات Provider
| القدرة | OpenAI | Google | fal | MiniMax | ComfyUI | Vydra | xAI |
| --------------------- | -------------------- | -------------------- | ------------------- | -------------------------- | ---------------------------------- | ------- | -------------------- |
| التوليد | نعم (حتى 4) | نعم (حتى 4) | نعم (حتى 4) | نعم (حتى 9) | نعم (مخرجات يحددها workflow) | نعم (1) | نعم (حتى 4) |
| التحرير/المرجع | نعم (حتى 5 صور) | نعم (حتى 5 صور) | نعم (صورة واحدة) | نعم (صورة واحدة، مرجع للموضوع) | نعم (صورة واحدة، وفق workflow) | لا | نعم (حتى 5 صور) |
| التحكم في الحجم | نعم (حتى 4K) | نعم | نعم | لا | لا | لا | لا |
| نسبة العرض إلى الارتفاع | لا | نعم | نعم (للتوليد فقط) | نعم | لا | لا | نعم |
| الدقة (1K/2K/4K) | لا | نعم | نعم | لا | لا | لا | نعم (1K/2K) |
| القدرة | OpenAI | Google | fal | MiniMax | ComfyUI | Vydra | xAI |
| --------------------- | ------------------ | ------------------ | ------------------ | --------------------------- | --------------------------------- | ------- | ------------------- |
| إنشاء | نعم (حتى 4) | نعم (حتى 4) | نعم (حتى 4) | نعم (حتى 9) | نعم (مخرجات يحددها سير العمل) | نعم (1) | نعم (حتى 4) |
| تحرير/مرجع | نعم (حتى 5 صور) | نعم (حتى 5 صور) | نعم (صورة واحدة) | نعم (صورة واحدة، مرجع موضوع) | نعم (صورة واحدة، وفق سير العمل) | لا | نعم (حتى 5 صور) |
| التحكم في الحجم | نعم (حتى 4K) | نعم | نعم | لا | لا | لا | لا |
| نسبة الأبعاد | لا | نعم | نعم (للإنشاء فقط) | نعم | لا | لا | نعم |
| الدقة (1K/2K/4K) | لا | نعم | نعم | لا | لا | لا | نعم (1K/2K) |
### xAI `grok-imagine-image`
يستخدم مزوّد xAI المضمّن `/v1/images/generations` لطلبات
prompt فقط، ويستخدم `/v1/images/edits` عندما تكون `image` أو `images` موجودة.
يستخدم xAI Provider المضمّن المسار `/v1/images/generations` للطلبات المعتمدة على المطالبة فقط
والمسار `/v1/images/edits` عندما تكون `image` أو `images` موجودة.
- النماذج: `xai/grok-imagine-image`، `xai/grok-imagine-image-pro`
- العدد: حتى 4
- المراجع: `image` واحدة أو حتى خمس `images`
- نسب العرض إلى الارتفاع: `1:1` و`16:9` و`9:16` و`4:3` و`3:4` و`2:3` و`3:2`
- نسب الأبعاد: `1:1`، `16:9`، `9:16`، `4:3`، `3:4`، `2:3`، `3:2`
- الدقات: `1K`، `2K`
- المخرجات: تُعاد كمرفقات صور مُدارة بواسطة OpenClaw
- المخرجات: تُعاد كمرفقات صور يديرها OpenClaw
يتعمد OpenClaw عدم كشف القيم الأصلية الخاصة بـ xAI مثل `quality` أو `mask` أو `user` أو
نسب العرض إلى الارتفاع الإضافية الأصلية فقط إلى أن تصبح هذه العناصر موجودة في
العقد المشترك `image_generate` عبر المزوّدات.
يتعمد OpenClaw عدم إظهار عناصر التحكم الأصلية الخاصة بـ xAI مثل `quality` و`mask` و`user` أو
نسب الأبعاد الإضافية الخاصة بالواجهة الأصلية إلى أن تتوفر تلك العناصر ضمن
عقدة `image_generate` المشتركة عبر موفري الخدمة.
## ذو صلة
- [نظرة عامة على الأدوات](/ar/tools) — جميع أدوات الوكيل المتاحة
- [fal](/ar/providers/fal) — إعداد مزوّد الصور والفيديو fal
- [ComfyUI](/ar/providers/comfy) — إعداد local ComfyUI وComfy Cloud workflow
- [Google (Gemini)](/ar/providers/google) — إعداد مزوّد الصور Gemini
- [MiniMax](/ar/providers/minimax) — إعداد مزوّد الصور MiniMax
- [OpenAI](/ar/providers/openai) — إعداد مزوّد OpenAI Images
- [Vydra](/ar/providers/vydra) — إعداد الصور والفيديو والكلام في Vydra
- [xAI](/ar/providers/xai) — إعداد Grok للصور والفيديو والبحث وتنفيذ الشيفرة وTTS
- [مرجع التهيئة](/ar/gateway/configuration-reference#agent-defaults) — تهيئة `imageGenerationModel`
- [النماذج](/ar/concepts/models) — تهيئة النموذج وfailover
- [fal](/ar/providers/fal) — إعداد fal لموفر الصور والفيديو
- [ComfyUI](/ar/providers/comfy) — إعداد ComfyUI المحلي وComfy Cloud وسير العمل
- [Google (Gemini)](/ar/providers/google) — إعداد موفر صور Gemini
- [MiniMax](/ar/providers/minimax) — إعداد موفر صور MiniMax
- [OpenAI](/ar/providers/openai) — إعداد موفر OpenAI Images
- [Vydra](/ar/providers/vydra) — إعداد Vydra للصور والفيديو والكلام
- [xAI](/ar/providers/xai) — إعداد Grok للصور والفيديو والبحث وتنفيذ الكود وTTS
- [مرجع التكوين](/ar/gateway/configuration-reference#agent-defaults) — تكوين `imageGenerationModel`
- [Models](/ar/concepts/models) — تكوين النماذج والرجوع الاحتياطي

277
docs/ar/tools/plugin.md
View File

@ -1,32 +1,32 @@
---
read_when:
- تثبيت Plugins أو تهيئتها
- فهم قواعد اكتشاف Plugin وتحميلها
- العمل مع حزم Plugin المتوافقة مع Codex/Claude
- فهم قواعد اكتشاف Plugin وتحميله
- العمل مع حِزم Plugin المتوافقة مع Codex/Claude
sidebarTitle: Install and Configure
summary: ثبّت Plugins الخاصة بـ OpenClaw وهيئها وأدرها
summary: ثبّت Plugins في OpenClaw وهيئها وأدرها
title: Plugins
x-i18n:
generated_at: "2026-04-23T07:33:52Z"
generated_at: "2026-04-23T14:03:01Z"
model: gpt-5.4
provider: openai
source_hash: dc944b53654552ca5cf6132c6ef16c71745a7bffc249daccaee40c513e04209c
source_hash: 63aa1b5ed9e3aaa2117b78137a457582b00ea47d94af7da3780ddae38e8e3665
source_path: tools/plugin.md
workflow: 15
---
# Plugins
توسّع Plugins قدرات OpenClaw بإضافة إمكانات جديدة: القنوات، ومزوّدي النماذج،
والأدوات، وSkills، والكلام، والنسخ الفوري، والصوت الفوري،
توسّع Plugins قدرات OpenClaw بإمكانات جديدة: القنوات، ومزوّدو النماذج،
والأدوات، وSkills، والصوت، والنسخ الفوري، والصوت الفوري،
وفهم الوسائط، وتوليد الصور، وتوليد الفيديو، وجلب الويب، وبحث الويب،
وغير ذلك. بعض Plugins تكون **أساسية** (تأتي مع OpenClaw)، وأخرى
**خارجية** (تنشرها المجتمع على npm).
وغير ذلك. بعض Plugins تكون **أساسية** (تُشحن مع OpenClaw)، وأخرى
**خارجية** (تنشرها community على npm).
## البدء السريع
<Steps>
<Step title="اعرف ما الذي تم تحميله">
<Step title="اطلع على ما تم تحميله">
```bash
openclaw plugins list
```
@ -37,7 +37,7 @@ x-i18n:
# من npm
openclaw plugins install @openclaw/voice-call
# من دليل أو أرشيف محلي
# من دليل محلي أو أرشيف
openclaw plugins install ./my-plugin
openclaw plugins install ./my-plugin.tgz
```
@ -49,12 +49,12 @@ x-i18n:
openclaw gateway restart
```
ثم قم بالتهيئة تحت `plugins.entries.\<id\>.config` في ملف الإعدادات لديك.
ثم اضبط الإعدادات تحت `plugins.entries.\<id\>.config` في ملف config الخاص بك.
</Step>
</Steps>
إذا كنت تفضّل التحكم الأصلي عبر الدردشة، فعطّل `commands.plugins: true` واستخدم:
إذا كنت تفضل التحكم الأصلي عبر الدردشة، فعّل `commands.plugins: true` واستخدم:
```text
/plugin install clawhub:@openclaw/voice-call
@ -62,33 +62,33 @@ x-i18n:
/plugin enable voice-call
```
يستخدم مسار التثبيت المحلل نفسه الموجود في CLI: مسار/أرشيف محلي، أو
`clawhub:<pkg>` صريح، أو مواصفة حزمة مجردة (ClawHub أولًا، ثم العودة إلى npm).
يستخدم مسار التثبيت نفس أداة الحل مثل CLI: مسار/أرشيف محلي، أو
`clawhub:<pkg>` صريح، أو مواصفة حزمة مجردة (ClawHub أولًا، ثم الرجوع إلى npm).
إذا كانت الإعدادات غير صالحة، فإن التثبيت يفشل عادةً بشكل مغلق ويوجهك إلى
`openclaw doctor --fix`. والاستثناء الوحيد للاستعادة هو مسار ضيق لإعادة تثبيت Plugin
مضمّنة تختار الاشتراك في
إذا كان config غير صالح، فعادةً ما يفشل التثبيت بشكل مغلق ويشير بك إلى
`openclaw doctor --fix`. والاستثناء الوحيد للاسترداد هو مسار ضيق لإعادة تثبيت
Plugin مضمّن لـ Plugins التي تشترك في
`openclaw.install.allowInvalidConfigRecovery`.
لا تقوم عمليات تثبيت OpenClaw المجمّعة بتثبيت شجرة تبعيات وقت التشغيل لكل Plugin مضمّنة
بشكل مسبق. وعندما تكون Plugin مضمّنة مملوكة لـ OpenClaw نشطة من
إعدادات Plugin، أو من إعدادات قنوات قديمة، أو من manifest مفعّل افتراضيًا، فإن
إصلاحات بدء التشغيل تصلح فقط تبعيات وقت التشغيل المعلنة لذلك Plugin قبل استيرادها.
أما Plugins الخارجية ومسارات التحميل المخصصة فلا تزال بحاجة إلى التثبيت عبر
لا تقوم تثبيتات OpenClaw المعبأة بتثبيت شجرة تبعيات وقت التشغيل لكل Plugin مضمّن
بشكل استباقي. وعندما يكون Plugin مضمّن ومملوك لـ OpenClaw نشطًا من خلال
config الخاص بالـ Plugin، أو config القناة القديم، أو manifest مفعّل افتراضيًا،
فإن إصلاحات بدء التشغيل تصلح فقط تبعيات وقت التشغيل المعلنة لذلك Plugin قبل استيراده.
أما Plugins الخارجية ومسارات التحميل المخصصة فما زالت تحتاج إلى التثبيت عبر
`openclaw plugins install`.
## أنواع Plugin
## أنواع Plugins
يتعرف OpenClaw على نوعين من صيغ Plugin:
يتعرف OpenClaw على تنسيقي Plugin:
| الصيغة | كيف تعمل | أمثلة |
| التنسيق | طريقة العمل | أمثلة |
| ---------- | ------------------------------------------------------------------ | ------------------------------------------------------ |
| **أصلية** | `openclaw.plugin.json` + وحدة runtime؛ تُنفَّذ داخل العملية | Plugins رسمية، وحزم npm من المجتمع |
| **Bundle** | تخطيط متوافق مع Codex/Claude/Cursor؛ ويُربط بميزات OpenClaw | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` |
| **Native** | `openclaw.plugin.json` + وحدة runtime؛ يُنفّذ داخل العملية | Plugins الرسمية، وحزم npm من community |
| **Bundle** | تخطيط متوافق مع Codex/Claude/Cursor؛ يُربط بميزات OpenClaw | `.codex-plugin/`، `.claude-plugin/`، `.cursor-plugin/` |
يظهر كلاهما تحت `openclaw plugins list`. راجع [حزم Plugin](/ar/plugins/bundles) للحصول على تفاصيل الحزم.
يظهر كلاهما ضمن `openclaw plugins list`. راجع [Plugin Bundles](/ar/plugins/bundles) لتفاصيل الحِزم.
إذا كنت تكتب Plugin أصلية، فابدأ من [بناء Plugins](/ar/plugins/building-plugins)
إذا كنت تكتب Plugin Native، فابدأ من [بناء Plugins](/ar/plugins/building-plugins)
و[نظرة عامة على Plugin SDK](/ar/plugins/sdk-overview).
## Plugins الرسمية
@ -104,33 +104,33 @@ x-i18n:
| Zalo | `@openclaw/zalo` | [Zalo](/ar/channels/zalo) |
| Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/ar/plugins/zalouser) |
### أساسية (تأتي مع OpenClaw)
### أساسية (تُشحن مع OpenClaw)
<AccordionGroup>
<Accordion title="موفرو النماذج (مفعّلون افتراضيًا)">
`anthropic`, `byteplus`, `cloudflare-ai-gateway`, `github-copilot`, `google`,
`huggingface`, `kilocode`, `kimi-coding`, `minimax`, `mistral`, `qwen`,
`moonshot`, `nvidia`, `openai`, `opencode`, `opencode-go`, `openrouter`,
`qianfan`, `synthetic`, `together`, `venice`,
`vercel-ai-gateway`, `volcengine`, `xiaomi`, `zai`
<Accordion title="مزودو النماذج (مفعّلون افتراضيًا)">
`anthropic`، `byteplus`، `cloudflare-ai-gateway`، `github-copilot`، `google`،
`huggingface`، `kilocode`، `kimi-coding`، `minimax`، `mistral`، `qwen`،
`moonshot`، `nvidia`، `openai`، `opencode`، `opencode-go`، `openrouter`،
`qianfan`، `synthetic`، `together`، `venice`،
`vercel-ai-gateway`، `volcengine`، `xiaomi`، `zai`
</Accordion>
<Accordion title="Plugins الذاكرة">
- `memory-core` — بحث ذاكرة مضمّن (الافتراضي عبر `plugins.slots.memory`)
- `memory-lancedb` — ذاكرة طويلة الأمد بتثبيت عند الطلب مع الاستدعاء/الالتقاط التلقائيين (اضبط `plugins.slots.memory = "memory-lancedb"`)
- `memory-core` — بحث الذاكرة المضمّن (الافتراضي عبر `plugins.slots.memory`)
- `memory-lancedb` — ذاكرة طويلة الأمد تُثبّت عند الطلب مع auto-recall/capture (اضبط `plugins.slots.memory = "memory-lancedb"`)
</Accordion>
<Accordion title="موفرو الكلام (مفعّلون افتراضيًا)">
`elevenlabs`, `microsoft`
<Accordion title="مزودو الصوت (مفعّلون افتراضيًا)">
`elevenlabs`، `microsoft`
</Accordion>
<Accordion title="أخرى">
- `browser` — Plugin متصفح مضمّنة لأداة المتصفح، وCLI ‏`openclaw browser`, وطريقة gateway ‏`browser.request`, وبيئة تشغيل المتصفح، وخدمة التحكم في المتصفح الافتراضية (مفعلة افتراضيًا؛ عطّلها قبل استبدالها)
- `copilot-proxy` — جسر VS Code Copilot Proxy (معطل افتراضيًا)
- `browser` — Plugin browser مضمّن لأداة browser، وCLI ‏`openclaw browser`، وطريقة Gateway ‏`browser.request`، وruntime الخاصة بالـ browser، وخدمة التحكم الافتراضية للـ browser (مفعّل افتراضيًا؛ عطّله قبل استبداله)
- `copilot-proxy` — جسر VS Code Copilot Proxy ‏(معطّل افتراضيًا)
</Accordion>
</AccordionGroup>
هل تبحث عن Plugins خارجية؟ راجع [Plugins المجتمع](/ar/plugins/community).
هل تبحث عن Plugins خارجية؟ راجع [Community Plugins](/ar/plugins/community).
## الإعدادات
@ -150,58 +150,58 @@ x-i18n:
| الحقل | الوصف |
| ---------------- | --------------------------------------------------------- |
| `enabled` | المفتاح الرئيسي (الافتراضي: `true`) |
| `allow` | قائمة سماح Plugin (اختياري) |
| `deny` | قائمة حظر Plugin (اختيارية؛ الحظر يتغلب) |
| `enabled` | مفتاح التبديل الرئيسي (الافتراضي: `true`) |
| `allow` | قائمة سماح Plugins (اختياري) |
| `deny` | قائمة حظر Plugins (اختياري؛ والحظر يتقدم) |
| `load.paths` | ملفات/أدلة Plugin إضافية |
| `slots` | محددات الخانات الحصرية (مثل `memory`, `contextEngine`) |
| `entries.\<id\>` | مفاتيح تفعيل + إعدادات لكل Plugin |
| `slots` | محددات slots حصرية (مثل `memory` و`contextEngine`) |
| `entries.\<id\>` | مفاتيح تبديل + config لكل Plugin |
تتطلب تغييرات الإعدادات **إعادة تشغيل gateway**. وإذا كانت Gateway تعمل مع
مراقبة الإعدادات + إعادة التشغيل داخل العملية مفعّلتين (وهو المسار الافتراضي `openclaw gateway`)،
فعادةً ما تُنفذ إعادة التشغيل هذه تلقائيًا بعد لحظة من وصول كتابة الإعدادات.
تتطلب تغييرات config **إعادة تشغيل gateway**. وإذا كانت Gateway تعمل مع
مراقبة config + إعادة تشغيل داخل العملية مفعّلتين (وهذا هو المسار الافتراضي `openclaw gateway`)،
فعادةً ما يتم تنفيذ إعادة التشغيل تلك تلقائيًا بعد لحظات من وصول كتابة config.
<Accordion title="حالات Plugin: معطلة مقابل مفقودة مقابل غير صالحة">
- **معطلة**: الـ Plugin موجودة لكن قواعد التفعيل عطلتها. وتظل الإعدادات محفوظة.
- **مفقودة**: تشير الإعدادات إلى معرّف Plugin لم يعثر عليه الاكتشاف.
- **غير صالحة**: الـ Plugin موجودة لكن إعداداتها لا تطابق المخطط المعلن.
<Accordion title="حالات Plugin: معطّل مقابل مفقود مقابل غير صالح">
- **معطّل**: Plugin موجود لكن قواعد التمكين عطّلته. ويتم الاحتفاظ بـ config.
- **مفقود**: يشير config إلى معرّف Plugin لم يعثر عليه الاكتشاف.
- **غير صالح**: Plugin موجود لكن config الخاص به لا يطابق schema المعلنة.
</Accordion>
## الاكتشاف والأولوية
## الاكتشاف والأسبقية
يفحص OpenClaw Plugins بهذا الترتيب (أول تطابق هو الفائز):
يفحص OpenClaw Plugins بهذا الترتيب (أول تطابق يفوز):
<Steps>
<Step title="مسارات الإعدادات">
<Step title="مسارات config">
`plugins.load.paths` — مسارات ملفات أو أدلة صريحة.
</Step>
<Step title="Plugins مساحة العمل">
`\<workspace\>/.openclaw/<plugin-root>/*.ts` و`\<_workspace\>/.openclaw/<plugin-root>/*/index.ts`.
`\<workspace\>/.openclaw/<plugin-root>/*.ts` و `\<workspace\>/.openclaw/<plugin-root>/*/index.ts`.
</Step>
<Step title="Plugins العامة">
`~/.openclaw/<plugin-root>/*.ts` و`~/.openclaw/<plugin-root>/*/index.ts`.
`~/.openclaw/<plugin-root>/*.ts` و `~/.openclaw/<plugin-root>/*/index.ts`.
</Step>
<Step title="Plugins المضمّنة">
تأتي مع OpenClaw. كثير منها مفعّل افتراضيًا (موفرو النماذج، والكلام).
ويتطلب بعضها الآخر تفعيلًا صريحًا.
تُشحن مع OpenClaw. كثير منها مفعّل افتراضيًا (مزودو النماذج، الصوت).
وأخرى تتطلب تمكينًا صريحًا.
</Step>
</Steps>
### قواعد التفعيل
### قواعد التمكين
- `plugins.enabled: false` يعطل جميع Plugins
- تتغلب `plugins.deny` دائمًا على allow
- `plugins.entries.\<id\>.enabled: false` يعطل تلك الـ Plugin
- Plugins ذات أصل مساحة العمل تكون **معطلة افتراضيًا** (ويجب تفعيلها صراحةً)
- يؤدي `plugins.enabled: false` إلى تعطيل كل Plugins
- يتقدم `plugins.deny` دائمًا على allow
- يؤدي `plugins.entries.\<id\>.enabled: false` إلى تعطيل ذلك Plugin
- تكون Plugins ذات أصل مساحة العمل **معطّلة افتراضيًا** (ويجب تمكينها صراحةً)
- تتبع Plugins المضمّنة مجموعة التفعيل الافتراضية المدمجة ما لم يتم تجاوزها
- يمكن للخانات الحصرية فرض تفعيل Plugin المحددة لتلك الخانة
- يمكن أن تفرض slots الحصرية تمكين Plugin المحدد لذلك slot
## خانات Plugin (فئات حصرية)
## Plugin slots (فئات حصرية)
بعض الفئات حصرية (يمكن أن تكون واحدة فقط نشطة في كل مرة):
بعض الفئات حصرية (واحد نشط فقط في كل مرة):
```json5
{
@ -214,37 +214,37 @@ x-i18n:
}
```
| الخانة | ما الذي تتحكم به | الافتراضي |
| الـ Slot | ما الذي يتحكم فيه | الافتراضي |
| --------------- | --------------------- | ------------------- |
| `memory` | Plugin الذاكرة النشطة | `memory-core` |
| `contextEngine` | محرك السياق النشط | `legacy` (مدمج) |
| `memory` | Plugin الذاكرة النشط | `memory-core` |
| `contextEngine` | محرك السياق النشط | `legacy` (مضمّن) |
## مرجع CLI
```bash
openclaw plugins list # جرد مضغوط
openclaw plugins list # فهرس مضغوط
openclaw plugins list --enabled # Plugins المحمّلة فقط
openclaw plugins list --verbose # أسطر تفاصيل لكل Plugin
openclaw plugins list --json # جرد قابل للقراءة الآلية
openclaw plugins list --json # فهرس قابل للقراءة آليًا
openclaw plugins inspect <id> # تفاصيل عميقة
openclaw plugins inspect <id> --json # قابل للقراءة الآلية
openclaw plugins inspect <id> --json # قابل للقراءة آليًا
openclaw plugins inspect --all # جدول على مستوى الأسطول
openclaw plugins info <id> # اسم مستعار لـ inspect
openclaw plugins doctor # diagnostics
openclaw plugins info <id> # اسم بديل لـ inspect
openclaw plugins doctor # تشخيصات
openclaw plugins install <package> # تثبيت (ClawHub أولًا، ثم npm)
openclaw plugins install clawhub:<pkg> # تثبيت من ClawHub فقط
openclaw plugins install <spec> --force # الكتابة فوق تثبيت موجود
openclaw plugins install <spec> --force # الكتابة فوق التثبيت الموجود
openclaw plugins install <path> # تثبيت من مسار محلي
openclaw plugins install -l <path> # ربط (من دون نسخ) للتطوير
openclaw plugins install <plugin> --marketplace <source>
openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo>
openclaw plugins install <spec> --pin # تسجيل مواصفة npm المحلولة الدقيقة
openclaw plugins install <spec> --dangerously-force-unsafe-install
openclaw plugins update <id-or-npm-spec> # تحديث Plugin واحدة
openclaw plugins update <id-or-npm-spec> # تحديث Plugin واحد
openclaw plugins update <id-or-npm-spec> --dangerously-force-unsafe-install
openclaw plugins update --all # تحديث الكل
openclaw plugins uninstall <id> # إزالة سجلات الإعداد/التثبيت
openclaw plugins uninstall <id> # إزالة سجلات config/التثبيت
openclaw plugins uninstall <id> --keep-files
openclaw plugins marketplace list <source>
openclaw plugins marketplace list <source> --json
@ -253,57 +253,63 @@ openclaw plugins enable <id>
openclaw plugins disable <id>
```
تأتي Plugins المضمّنة مع OpenClaw. وكثير منها مفعّل افتراضيًا (مثل
موفري النماذج المضمّنين، وموفري الكلام المضمّنين، وPlugin المتصفح
المضمّنة). أما Plugins المضمّنة الأخرى فما تزال بحاجة إلى `openclaw plugins enable <id>`.
تُشحن Plugins المضمّنة مع OpenClaw. كثير منها مفعّل افتراضيًا (على سبيل المثال
مزودو النماذج المضمّنون، ومزودو الصوت المضمّنون، وPlugin
browser المضمّن). وما تزال Plugins مضمّنة أخرى تحتاج إلى `openclaw plugins enable <id>`.
يقوم `--force` بالكتابة فوق Plugin أو حزمة hook مثبّتة موجودة بالفعل في مكانها. استخدم
`openclaw plugins update <id-or-npm-spec>` للترقيات المعتادة لـ Plugins npm
المتتبعة. ولا يُدعم هذا الخيار مع `--link`, الذي يعيد استخدام مسار المصدر بدلًا
يقوم `--force` بالكتابة فوق Plugin أو hook pack مثبت موجود في مكانه. استخدم
`openclaw plugins update <id-or-npm-spec>` للترقيات الروتينية لـ Plugins npm
المتتبعة. وهو غير مدعوم مع `--link`، الذي يعيد استخدام مسار المصدر بدلًا
من النسخ فوق هدف تثبيت مُدار.
عندما تكون `plugins.allow` مضبوطة بالفعل، يضيف `openclaw plugins install`
معرّف Plugin المثبّت إلى قائمة السماح تلك قبل تمكينه، بحيث تصبح عمليات التثبيت
قابلة للتحميل فورًا بعد إعادة التشغيل.
ينطبق `openclaw plugins update <id-or-npm-spec>` على التثبيتات المتتبعة. ويؤدي تمرير
مواصفة حزمة npm مع dist-tag أو إصدار دقيق إلى حل اسم الحزمة
إلى سجل Plugin المتتبَّع وتسجيل المواصفة الجديدة لأجل التحديثات المستقبلية.
أما تمرير اسم الحزمة من دون إصدار فيعيد تثبيتًا دقيقًا مثبتًا إلى
خط الإصدار الافتراضي في السجل. وإذا كانت Plugin npm المثبتة تطابق بالفعل
الإصدار المحلول وهوية العنصر المسجلة، فإن OpenClaw يتجاوز التحديث
من دون تنزيل أو إعادة تثبيت أو إعادة كتابة الإعدادات.
مجدّدًا إلى سجل Plugin المتتبع وتسجيل المواصفة الجديدة للتحديثات المستقبلية.
ويؤدي تمرير اسم الحزمة من دون إصدار إلى إعادة تثبيت دقيق ومثبت إلى
خط الإصدار الافتراضي للسجل. وإذا كان Plugin npm المثبّت يطابق بالفعل
الإصدار المحلول وهوية artifact المسجلة، فإن OpenClaw يتخطى التحديث
من دون تنزيل أو إعادة تثبيت أو إعادة كتابة config.
إن `--pin` خاص بـ npm فقط. وهو غير مدعوم مع `--marketplace`, لأن
تثبيتات marketplace تحفظ بيانات وصفية لمصدر marketplace بدلًا من مواصفة npm.
`--pin` خاص بـ npm فقط. وهو غير مدعوم مع `--marketplace`، لأن
تثبيتات marketplace تحفظ بيانات مصدر marketplace الوصفية بدلًا من مواصفة npm.
إن `--dangerously-force-unsafe-install` هو تجاوز كسر زجاج للحالات الإيجابية
الخاطئة من ماسح الشيفرة الخطرة المدمج. فهو يسمح لتثبيتات Plugin
وتحديثاتها بالاستمرار رغم وجود نتائج `critical` من الفحص المدمج، لكنه
ما يزال لا يتجاوز كتل سياسة `before_install` الخاصة بـ Plugin أو منع فشل الفحص.
`--dangerously-force-unsafe-install` هو تجاوز break-glass للحالات
الإيجابية الكاذبة من dangerous-code scanner المضمّن. وهو يسمح باستمرار
عمليات تثبيت Plugin وتحديثاته بعد نتائج `critical` المضمنة، لكنه
لا يتجاوز حظر السياسة `before_install` الخاصة بالـ Plugin أو الحظر الناتج عن فشل الفحص.
ينطبق هذا الخيار في CLI على تدفقات تثبيت/تحديث Plugin فقط. أما تثبيتات تبعيات Skill
المدعومة بـ Gateway فتستخدم بدلًا من ذلك تجاوز الطلب المطابق `dangerouslyForceUnsafeInstall`,
بينما يبقى `openclaw skills install` تدفق تنزيل/تثبيت Skills منفصلًا من ClawHub.
ينطبق هذا العلم في CLI على تدفقات تثبيت/تحديث Plugin فقط. أما عمليات تثبيت
تبعيات Skills المدعومة من Gateway فتستخدم التجاوز المطابق للطلب
`dangerouslyForceUnsafeInstall` بدلًا من ذلك، بينما يظل `openclaw skills install`
هو تدفق التنزيل/التثبيت المنفصل لـ Skills من ClawHub.
تشارك الحزم المتوافقة في التدفق نفسه لـ list/inspect/enable/disable الخاص بالـ Plugin.
ويشمل دعم بيئة التشغيل الحالي Skills الحزمة، وClaude command-skills,
وقيم Claude الافتراضية في `settings.json`, وClaude `.lsp.json` و
القيم الافتراضية `lspServers` المعلنة في manifest, وCursor command-skills،
وأدلة hook المتوافقة مع Codex.
تشارك الحِزم المتوافقة في نفس تدفق list/inspect/enable/disable الخاص بالـ Plugin.
ويتضمن دعم runtime الحالي Skills الخاصة بالحِزم، وClaude command-skills،
وقيم Claude ‏`settings.json` الافتراضية، وقيم Claude ‏`.lsp.json` و
القيم الافتراضية `lspServers` المعلنة في manifest، وCursor command-skills،
وأدلة hooks المتوافقة مع Codex.
ويُبلغ `openclaw plugins inspect <id>` أيضًا عن قدرات الحزمة المكتشفة إضافةً إلى
إدخالات MCP وLSP server المدعومة أو غير المدعومة الخاصة بالـ Plugins المدعومة بالحزم.
يبلغ `openclaw plugins inspect <id>` أيضًا عن إمكانات الحِزمة المكتشفة بالإضافة
إلى إدخالات خوادم MCP وLSP المدعومة أو غير المدعومة لـ Plugins
المدعومة بالحِزم.
يمكن أن تكون مصادر Marketplace اسم marketplace معروفًا لـ Claude من
`~/.claude/plugins/known_marketplaces.json`, أو جذر marketplace محليًا، أو
مسار `marketplace.json`, أو صيغة GitHub مختصرة مثل `owner/repo`, أو عنوان URL لمستودع GitHub،
أو عنوان URL لـ git. وبالنسبة إلى marketpaces البعيدة، يجب أن تبقى إدخالات Plugin داخل
مستودع marketplace المستنسخ وأن تستخدم مصادر مسارات نسبية فقط.
يمكن أن تكون مصادر Marketplace اسم known-marketplace خاصًا بـ Claude من
`~/.claude/plugins/known_marketplaces.json`، أو جذر Marketplace محلي أو
مسار `marketplace.json`، أو اختصار GitHub مثل `owner/repo`، أو عنوان URL لمستودع GitHub،
أو عنوان URL لـ git. وبالنسبة إلى Marketplaces البعيدة، يجب أن تبقى إدخالات Plugin داخل
مستودع Marketplace المستنسخ وأن تستخدم مصادر مسارات نسبية فقط.
راجع [مرجع CLI للأمر `openclaw plugins`](/ar/cli/plugins) للحصول على التفاصيل الكاملة.
راجع [مرجع CLI ‏`openclaw plugins`](/ar/cli/plugins) للاطلاع على التفاصيل الكاملة.
## نظرة عامة على Plugin API
تُصدّر Plugins الأصلية كائن إدخال يعرض `register(api)`. وقد
تستخدم Plugins الأقدم ما يزال `activate(api)` كاسم مستعار قديم، لكن Plugins الجديدة ينبغي أن
تستخدم `register`.
تُصدّر Plugins Native كائن إدخال يعرّض `register(api)`. وما زالت
Plugins الأقدم قد تستخدم `activate(api)` كاسم بديل قديم، لكن Plugins الجديدة يجب
أن تستخدم `register`.
```typescript
export default definePluginEntry({
@ -324,14 +330,15 @@ export default definePluginEntry({
```
يحمّل OpenClaw كائن الإدخال ويستدعي `register(api)` أثناء تفعيل Plugin.
وما يزال المحمّل يعود إلى `activate(api)` بالنسبة إلى Plugins الأقدم،
لكن يجب أن تتعامل Plugins المضمّنة وPlugins الخارجية الجديدة مع `register` على أنها العقد العام.
وما يزال loader يعود إلى `activate(api)` بالنسبة إلى Plugins الأقدم،
لكن يجب على Plugins المضمّنة وPlugins الخارجية الجديدة اعتبار `register`
العقد العام.
أساليب التسجيل الشائعة:
طرق التسجيل الشائعة:
| الطريقة | ما الذي تسجله |
| --------------------------------------- | --------------------------- |
| `registerProvider` | مزوّد نموذج (LLM) |
| `registerProvider` | مزود نماذج (LLM) |
| `registerChannel` | قناة دردشة |
| `registerTool` | أداة وكيل |
| `registerHook` / `on(...)` | hooks دورة الحياة |
@ -342,29 +349,29 @@ export default definePluginEntry({
| `registerImageGenerationProvider` | توليد الصور |
| `registerMusicGenerationProvider` | توليد الموسيقى |
| `registerVideoGenerationProvider` | توليد الفيديو |
| `registerWebFetchProvider` | مزوّد جلب / كشط الويب |
| `registerWebFetchProvider` | مزود جلب / كشط ويب |
| `registerWebSearchProvider` | بحث الويب |
| `registerHttpRoute` | نقطة نهاية HTTP |
| `registerCommand` / `registerCli` | أوامر CLI |
| `registerContextEngine` | محرك سياق |
| `registerContextEngine` | محرك السياق |
| `registerService` | خدمة في الخلفية |
سلوك حواجز hook الخاصة بـ hooks دورة الحياة المtyped:
سلوك hook guard بالنسبة إلى hooks دورة الحياة المكتوبة:
- `before_tool_call`: تكون `{ block: true }` نهائية؛ ويتم تخطي المعالجات ذات الأولوية الأدنى.
- `before_tool_call`: تكون `{ block: false }` بلا تأثير ولا تمسح block سابقة.
- `before_tool_call`: تكون `{ block: false }` بلا تأثير ولا تزيل block سابقًا.
- `before_install`: تكون `{ block: true }` نهائية؛ ويتم تخطي المعالجات ذات الأولوية الأدنى.
- `before_install`: تكون `{ block: false }` بلا تأثير ولا تمسح block سابقة.
- `before_install`: تكون `{ block: false }` بلا تأثير ولا تزيل block سابقًا.
- `message_sending`: تكون `{ cancel: true }` نهائية؛ ويتم تخطي المعالجات ذات الأولوية الأدنى.
- `message_sending`: تكون `{ cancel: false }` بلا تأثير ولا تمسح cancel سابقة.
- `message_sending`: تكون `{ cancel: false }` بلا تأثير ولا تزيل cancel سابقًا.
للاطلاع على السلوك الكامل للـ hooks المtyped، راجع [نظرة عامة على SDK](/ar/plugins/sdk-overview#hook-decision-semantics).
للاطلاع على السلوك الكامل للـ hooks المكتوبة، راجع [نظرة عامة على SDK](/ar/plugins/sdk-overview#hook-decision-semantics).
## ذو صلة
- [بناء Plugins](/ar/plugins/building-plugins) — أنشئ Plugin الخاصة بك
- [حزم Plugin](/ar/plugins/bundles) — توافق حزم Codex/Claude/Cursor
- [بيان Plugin](/ar/plugins/manifest) — مخطط manifest
- [تسجيل الأدوات](/ar/plugins/building-plugins#registering-agent-tools) — أضف أدوات الوكيل في Plugin
- [الداخليات الخاصة بـ Plugin](/ar/plugins/architecture) — نموذج القدرات ومسار التحميل
- [Plugins المجتمع](/ar/plugins/community) — قوائم الطرف الثالث
- [بناء Plugins](/ar/plugins/building-plugins) — أنشئ Plugin خاصًا بك
- [Plugin Bundles](/ar/plugins/bundles) — توافق حِزم Codex/Claude/Cursor
- [Plugin Manifest](/ar/plugins/manifest) — مخطط manifest
- [تسجيل الأدوات](/ar/plugins/building-plugins#registering-agent-tools) — أضف أدوات الوكيل داخل Plugin
- [Plugin Internals](/ar/plugins/architecture) — نموذج الإمكانات ومسار التحميل
- [Community Plugins](/ar/plugins/community) — قوائم الجهات الخارجية

353
docs/ar/tools/slash-commands.md
View File

@ -1,38 +1,38 @@
---
read_when:
- استخدام أو تكوين أوامر الدردشة
- استخدام أو إعداد أوامر الدردشة
- تصحيح توجيه الأوامر أو الأذونات
summary: 'أوامر الشرطة المائلة: النصية مقابل الأصلية، والإعدادات، والأوامر المدعومة'
summary: 'أوامر الشرطة المائلة: النصية مقابل الأصلية، والإعداد، والأوامر المدعومة'
title: أوامر الشرطة المائلة
x-i18n:
generated_at: "2026-04-23T07:34:10Z"
generated_at: "2026-04-23T14:03:12Z"
model: gpt-5.4
provider: openai
source_hash: 0f6b454afa77cf02b2c307efcc99ef35d002cb560c427affaf03ac12b2b666e8
source_hash: 13290dcdf649ae66603a92a0aca68460bb63ff476179cc2dded796aaa841d66c
source_path: tools/slash-commands.md
workflow: 15
---
# أوامر الشرطة المائلة
تُعالَج الأوامر بواسطة Gateway. ويجب إرسال معظم الأوامر كرسالة **مستقلة** تبدأ بـ `/`.
أما أمر دردشة bash الخاص بالمضيف فقط فيستخدم `! <cmd>` ‏(مع وجود `/bash <cmd>` كاسم بديل).
تتولى Gateway معالجة الأوامر. ويجب إرسال معظم الأوامر كرسالة **مستقلة** تبدأ بـ `/`.
ويستخدم أمر bash الخاص بالدردشة على المضيف فقط الصيغة `! <cmd>` (مع `/bash <cmd>` كاسم مستعار).
هناك نظامان مترابطان:
- **الأوامر**: رسائل مستقلة من نوع `/...`.
- **التوجيهات**: `/think`, `/fast`, `/verbose`, `/trace`, `/reasoning`, `/elevated`, `/exec`, `/model`, `/queue`.
- **الأوامر**: رسائل مستقلة من الشكل `/...`.
- **التوجيهات**: `/think` و`/fast` و`/verbose` و`/trace` و`/reasoning` و`/elevated` و`/exec` و`/model` و`/queue`.
- تُزال التوجيهات من الرسالة قبل أن يراها النموذج.
- في رسائل الدردشة العادية (وليست رسائل توجيهات فقط)، تُعامل على أنها “تلميحات مضمّنة” ولا **تستمر** كإعدادات للجلسة.
- في رسائل التوجيهات فقط (عندما تحتوي الرسالة على توجيهات فقط)، فإنها تستمر في الجلسة وترد بإقرار.
- لا تُطبَّق التوجيهات إلا على **المرسلين المصرّح لهم**. إذا كانت `commands.allowFrom` مضبوطة، فهي قائمة
السماح الوحيدة المستخدمة؛ وإلا تأتي المصادقة من قوائم السماح/الاقتران الخاصة بالقناة بالإضافة إلى `commands.useAccessGroups`.
ويرى المرسلون غير المصرّح لهم التوجيهات على أنها نص عادي.
- في رسائل الدردشة العادية (وليست الرسائل التي تحتوي على توجيهات فقط)، تُعامل على أنها "تلميحات مضمّنة" ولا **تستمر** كإعدادات للجلسة.
- في الرسائل التي تحتوي على توجيهات فقط (أي تحتوي الرسالة على توجيهات فقط)، تستمر في الجلسة وترد بإقرار.
- لا تُطبَّق التوجيهات إلا على **المرسلين المصرّح لهم**. وإذا كان `commands.allowFrom` مضبوطًا، فهو
قائمة السماح الوحيدة المستخدمة؛ وإلا فتأتي المصادقة من قوائم السماح/الاقتران الخاصة بالقناة بالإضافة إلى `commands.useAccessGroups`.
أما المرسلون غير المصرّح لهم فتُعامل التوجيهات لديهم كنص عادي.
كما توجد بعض **الاختصارات المضمّنة** (للمرسلين المدرجين في قائمة السماح/المصرّح لهم فقط): `/help`, `/commands`, `/status`, `/whoami` ‏(`/id`).
تُشغَّل هذه فورًا، وتُزال قبل أن يراها النموذج، ويستمر النص المتبقي عبر التدفق العادي.
وهناك أيضًا بعض **الاختصارات المضمّنة** (للمرسلين المدرجين في قائمة السماح/المصرّح لهم فقط): `/help` و`/commands` و`/status` و`/whoami` (`/id`).
فهي تعمل فورًا، وتُزال قبل أن يرى النموذج الرسالة، ويستمر النص المتبقي عبر التدفق العادي.
## الإعدادات
## الإعداد
```json5
{
@ -59,112 +59,112 @@ x-i18n:
}
```
- `commands.text` ‏(الافتراضي `true`) يفعّل تحليل `/...` داخل رسائل الدردشة.
- على الأسطح التي لا تدعم الأوامر الأصلية (WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams)، ستظل الأوامر النصية تعمل حتى إذا ضبطت هذه القيمة على `false`.
- `commands.native` ‏(الافتراضي `"auto"`) يسجل الأوامر الأصلية.
- Auto: مفعّل لـ Discord/Telegram؛ ومعطّل لـ Slack (حتى تضيف slash commands)؛ ويتم تجاهله للمزوّدين الذين لا يدعمون الأوامر الأصلية.
- اضبط `channels.discord.commands.native` أو `channels.telegram.commands.native` أو `channels.slack.commands.native` للتجاوز لكل مزوّد (قيمة منطقية أو `"auto"`).
- تؤدي القيمة `false` إلى مسح الأوامر المسجلة سابقًا على Discord/Telegram عند بدء التشغيل. أما أوامر Slack فتُدار في تطبيق Slack ولا تُزال تلقائيًا.
- `commands.nativeSkills` ‏(الافتراضي `"auto"`) يسجل أوامر **Skills** بشكل أصلي عند الدعم.
- Auto: مفعّل لـ Discord/Telegram؛ ومعطّل لـ Slack (يتطلب Slack إنشاء slash command لكل Skill).
- اضبط `channels.discord.commands.nativeSkills` أو `channels.telegram.commands.nativeSkills` أو `channels.slack.commands.nativeSkills` للتجاوز لكل مزوّد (قيمة منطقية أو `"auto"`).
- `commands.bash` ‏(الافتراضي `false`) يفعّل `! <cmd>` لتشغيل أوامر shell على المضيف (`/bash <cmd>` اسم بديل؛ ويتطلب قوائم سماح `tools.elevated`).
- يتحكم `commands.bashForegroundMs` ‏(الافتراضي `2000`) في مدة انتظار bash قبل التحول إلى الوضع الخلفي (`0` ينقله إلى الخلفية فورًا).
- `commands.config` ‏(الافتراضي `false`) يفعّل `/config` ‏(لقراءة/كتابة `openclaw.json`).
- `commands.mcp` ‏(الافتراضي `false`) يفعّل `/mcp` ‏(لقراءة/كتابة إعدادات MCP التي يديرها OpenClaw تحت `mcp.servers`).
- `commands.plugins` ‏(الافتراضي `false`) يفعّل `/plugins` ‏(اكتشاف Plugins/حالتها بالإضافة إلى عناصر التحكم في التثبيت + التمكين/التعطيل).
- `commands.debug` ‏(الافتراضي `false`) يفعّل `/debug` ‏(تجاوزات وقت التشغيل فقط).
- `commands.restart` ‏(الافتراضي `true`) يفعّل `/restart` بالإضافة إلى إجراءات أداة إعادة تشغيل gateway.
- `commands.ownerAllowFrom` ‏(اختياري) يضبط قائمة السماح الصريحة الخاصة بالمالك لأسطح الأوامر/الأدوات المخصصة للمالك فقط. وهذا منفصل عن `commands.allowFrom`.
- تجعل القيمة `channels.<channel>.commands.enforceOwnerForCommands` لكل قناة ‏(اختيارية، الافتراضي `false`) الأوامر الخاصة بالمالك فقط تتطلب **هوية المالك** للتشغيل على ذلك السطح. عندما تكون `true`، يجب أن يطابق المرسل إما مرشح مالك محلولًا (على سبيل المثال إدخالًا في `commands.ownerAllowFrom` أو بيانات مالك أصلية خاصة بالمزوّد) أو أن يحمل النطاق الداخلي `operator.admin` على قناة رسائل داخلية. ولا يكفي إدخال wildcard في `allowFrom` الخاصة بالقناة، أو قائمة مرشحي مالك فارغة/غير محلولة — إذ تفشل الأوامر الخاصة بالمالك فقط بشكل مغلق على تلك القناة. اترك هذا معطّلًا إذا كنت تريد أن تكون الأوامر الخاصة بالمالك فقط مقيّدة بـ `ownerAllowFrom` وقوائم السماح القياسية للأوامر فقط.
- يقوم `commands.text` (الافتراضي `true`) بتمكين تحليل `/...` في رسائل الدردشة.
- على الأسطح التي لا تحتوي على أوامر أصلية (WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams)، تظل الأوامر النصية تعمل حتى إذا ضبطت هذا على `false`.
- يقوم `commands.native` (الافتراضي `"auto"`) بتسجيل الأوامر الأصلية.
- Auto: مفعّل في Discord/Telegram؛ ومعطّل في Slack (إلى أن تضيف slash commands)؛ ويتم تجاهله لمزوّدي الخدمة الذين لا يدعمون الأوامر الأصلية.
- اضبط `channels.discord.commands.native` أو `channels.telegram.commands.native` أو `channels.slack.commands.native` لتجاوزه لكل مزوّد على حدة (قيمة منطقية أو `"auto"`).
- تقوم القيمة `false` بمسح الأوامر المسجلة سابقًا في Discord/Telegram عند بدء التشغيل. أما أوامر Slack فتُدار في تطبيق Slack ولا تُزال تلقائيًا.
- يقوم `commands.nativeSkills` (الافتراضي `"auto"`) بتسجيل أوامر **Skills** بشكل أصلي عند الدعم.
- Auto: مفعّل في Discord/Telegram؛ ومعطّل في Slack (يتطلب Slack إنشاء slash command لكل Skill).
- اضبط `channels.discord.commands.nativeSkills` أو `channels.telegram.commands.nativeSkills` أو `channels.slack.commands.nativeSkills` لتجاوزه لكل مزوّد على حدة (قيمة منطقية أو `"auto"`).
- يقوم `commands.bash` (الافتراضي `false`) بتمكين `! <cmd>` لتشغيل أوامر shell على المضيف (`/bash <cmd>` اسم مستعار؛ ويتطلب قوائم سماح `tools.elevated`).
- يتحكم `commands.bashForegroundMs` (الافتراضي `2000`) في المدة التي ينتظرها bash قبل التحول إلى وضع الخلفية (`0` ينقله إلى الخلفية فورًا).
- يقوم `commands.config` (الافتراضي `false`) بتمكين `/config` (قراءة/كتابة `openclaw.json`).
- يقوم `commands.mcp` (الافتراضي `false`) بتمكين `/mcp` (قراءة/كتابة إعداد MCP الذي يديره OpenClaw تحت `mcp.servers`).
- يقوم `commands.plugins` (الافتراضي `false`) بتمكين `/plugins` (اكتشاف الإضافات/الحالة بالإضافة إلى عناصر التحكم في التثبيت + التمكين/التعطيل).
- يقوم `commands.debug` (الافتراضي `false`) بتمكين `/debug` (تجاوزات وقت التشغيل فقط).
- يقوم `commands.restart` (الافتراضي `true`) بتمكين `/restart` بالإضافة إلى إجراءات أداة إعادة تشغيل Gateway.
- يضبط `commands.ownerAllowFrom` (اختياري) قائمة السماح الصريحة للمالك لأسطح الأوامر/الأدوات المخصصة للمالك فقط. وهذا منفصل عن `commands.allowFrom`.
- يجعل الخيار لكل قناة `channels.<channel>.commands.enforceOwnerForCommands` (اختياري، والافتراضي `false`) الأوامر المخصصة للمالك فقط تتطلب **هوية المالك** للتشغيل على ذلك السطح. وعندما تكون قيمته `true`، يجب أن يطابق المرسل إما مرشح مالك محلولًا (مثل إدخال في `commands.ownerAllowFrom` أو metadata أصلية للمالك من المزوّد) أو أن يملك النطاق الداخلي `operator.admin` على قناة رسائل داخلية. لا يُعد إدخال wildcard في `allowFrom` الخاصة بالقناة، أو قائمة مرشحي مالك فارغة/غير محلولة، **كافيًا** — إذ تفشل الأوامر الخاصة بالمالك فقط بشكل مغلق على تلك القناة. اترك هذا الخيار معطّلًا إذا كنت تريد أن تُقيَّد الأوامر الخاصة بالمالك فقط بواسطة `ownerAllowFrom` وقوائم سماح الأوامر القياسية.
- يتحكم `commands.ownerDisplay` في كيفية ظهور معرّفات المالك في system prompt: ‏`raw` أو `hash`.
- يضبط `commands.ownerDisplaySecret` اختياريًا سر HMAC المستخدم عندما تكون `commands.ownerDisplay="hash"`.
- تضبط `commands.allowFrom` ‏(اختيارية) قائمة سماح لكل مزوّد لمصادقة الأوامر. عند تكوينها، تكون
المصدر الوحيد للمصادقة بالنسبة إلى الأوامر والتوجيهات (ويتم تجاهل قوائم السماح/الاقتران الخاصة بالقناة و`commands.useAccessGroups`).
استخدم `"*"` كافتراضي عام؛ وتتجاوز المفاتيح الخاصة بكل مزوّد هذا الافتراضي.
- تفرض `commands.useAccessGroups` ‏(الافتراضي `true`) قوائم السماح/السياسات على الأوامر عندما لا تكون `commands.allowFrom` مضبوطة.
- يضبط `commands.ownerDisplaySecret` اختياريًا سر HMAC المستخدم عندما يكون `commands.ownerDisplay="hash"`.
- يضبط `commands.allowFrom` (اختياري) قائمة سماح لكل مزوّد من أجل تخويل الأوامر. وعند إعداده، يكون
مصدر التخويل الوحيد للأوامر والتوجيهات (ويتم تجاهل قوائم السماح/الاقتران الخاصة بالقناة و`commands.useAccessGroups`).
استخدم `"*"` كقيمة افتراضية عامة؛ وتتجاوز المفاتيح الخاصة بكل مزوّد هذه القيمة.
- يفرض `commands.useAccessGroups` (الافتراضي `true`) قوائم السماح/السياسات على الأوامر عندما لا يكون `commands.allowFrom` مضبوطًا.
## قائمة الأوامر
مصدر الحقيقة الحالي:
المصدر المرجعي الحالي:
- تأتي الأوامر الأساسية المضمنة من `src/auto-reply/commands-registry.shared.ts`
- تأتي أوامر dock المولدة من `src/auto-reply/commands-registry.data.ts`
- تأتي أوامر Plugin من استدعاءات `registerCommand()` الخاصة بالPlugin
- لا يزال التوفر الفعلي على Gateway الخاصة بك يعتمد على أعلام الإعدادات، وسطح القناة، وPlugins المثبتة/المفعّلة
- تأتي أوامر dock المولّدة من `src/auto-reply/commands-registry.data.ts`
- تأتي أوامر Plugin من استدعاءات `registerCommand()` في Plugin
- لا يزال التوفر الفعلي على Gateway لديك يعتمد على علامات الإعداد، وسطح القناة، والإضافات المثبتة/المفعّلة
### الأوامر الأساسية المضمنة
الأوامر المضمنة المتاحة اليوم:
- `/new [model]` يبدأ جلسة جديدة؛ و`/reset` هو الاسم البديل لإعادة التعيين.
- `/reset soft [message]` يحتفظ بالنص الحالي، ويسقط معرّفات جلسات الواجهة الخلفية لـ CLI المعاد استخدامها، ويعيد تشغيل تحميل startup/system-prompt في مكانه.
- `/compact [instructions]` يقوم بـ Compaction لسياق الجلسة. راجع [/concepts/compaction](/ar/concepts/compaction).
- `/stop` يوقف التشغيل الحالي.
- يدير `/session idle <duration|off>` و`/session max-age <duration|off>` انتهاء ارتباط السلسلة.
- يضبط `/think <level>` مستوى التفكير. تأتي الخيارات من ملف تعريف المزوّد الخاص بالنموذج النشط؛ والمستويات الشائعة هي `off` و`minimal` و`low` و`medium` و`high`، مع مستويات مخصصة مثل `xhigh` و`adaptive` و`max` أو `on` الثنائي فقط حيثما كان ذلك مدعومًا. الأسماء البديلة: `/thinking`, `/t`.
- يبدّل `/verbose on|off|full` المخرجات المطولة. الاسم البديل: `/v`.
- يبدّل `/trace on|off` خرج تتبع Plugin للجلسة الحالية.
- يبدأ `/new [model]` جلسة جديدة؛ و`/reset` هو الاسم المستعار لإعادة الضبط.
- يحتفظ `/reset soft [message]` بالنص الحالي، ويحذف معرّفات جلسات الواجهة الخلفية لـ CLI المعاد استخدامها، ويعيد تشغيل تحميل startup/system-prompt في المكان نفسه.
- يقوم `/compact [instructions]` بضغط سياق الجلسة. راجع [/concepts/compaction](/ar/concepts/compaction).
- يوقف `/stop` التشغيل الحالي.
- يدير `/session idle <duration|off>` و`/session max-age <duration|off>` انتهاء صلاحية ربط الخيط.
- يضبط `/think <level>` مستوى التفكير. تأتي الخيارات من ملف تعريف المزوّد للنموذج النشط؛ والمستويات الشائعة هي `off` و`minimal` و`low` و`medium` و`high`، مع مستويات مخصصة مثل `xhigh` و`adaptive` و`max` أو القيمة الثنائية `on` فقط حيث تكون مدعومة. الأسماء المستعارة: `/thinking` و`/t`.
- يبدّل `/verbose on|off|full` المخرجات المطوّلة. الاسم المستعار: `/v`.
- يبدّل `/trace on|off` مخرجات تتبع Plugin للجلسة الحالية.
- يعرض `/fast [status|on|off]` الوضع السريع أو يضبطه.
- يبدّل `/reasoning [on|off|stream]` إظهار الاستدلال. الاسم البديل: `/reason`.
- يبدّل `/elevated [on|off|ask|full]` الوضع المرتفع. الاسم البديل: `/elev`.
- يعرض `/exec host=<auto|sandbox|gateway|node> security=<deny|allowlist|full> ask=<off|on-miss|always> node=<id>` إعدادات exec الافتراضية أو يضبطها.
- يبدّل `/reasoning [on|off|stream]` إظهار الاستدلال. الاسم المستعار: `/reason`.
- يبدّل `/elevated [on|off|ask|full]` الوضع المرتفع الصلاحيات. الاسم المستعار: `/elev`.
- يعرض `/exec host=<auto|sandbox|gateway|node> security=<deny|allowlist|full> ask=<off|on-miss|always> node=<id>` الإعدادات الافتراضية للتنفيذ أو يضبطها.
- يعرض `/model [name|#|status]` النموذج أو يضبطه.
- يسرد `/models [provider] [page] [limit=<n>|size=<n>|all]` المزوّدين أو النماذج الخاصة بمزوّد ما.
- يدير `/queue <mode>` سلوك الطابور (`steer`, `interrupt`, `followup`, `collect`, `steer-backlog`) بالإضافة إلى خيارات مثل `debounce:2s cap:25 drop:summarize`.
- يعرض `/help` ملخص المساعدة المختصر.
- يسرد `/models [provider] [page] [limit=<n>|size=<n>|all]` المزوّدات أو نماذج مزوّد معيّن.
- يدير `/queue <mode>` سلوك قائمة الانتظار (`steer` و`interrupt` و`followup` و`collect` و`steer-backlog`) بالإضافة إلى خيارات مثل `debounce:2s cap:25 drop:summarize`.
- يعرض `/help` ملخص المساعدة القصير.
- يعرض `/commands` فهرس الأوامر المولّد.
- يعرض `/tools [compact|verbose]` ما الذي يمكن للوكيل الحالي استخدامه الآن.
- يعرض `/status` حالة وقت التشغيل، بما في ذلك استخدام المزوّد/الحصة عند توفرها.
- يعرض `/status` حالة وقت التشغيل، بما في ذلك التسميات `Runtime`/`Runner` واستخدام المزوّد/الحصة عند توفرها.
- يسرد `/tasks` المهام الخلفية النشطة/الأخيرة للجلسة الحالية.
- يشرح `/context [list|detail|json]` كيفية تجميع السياق.
- يصدّر `/export-session [path]` الجلسة الحالية إلى HTML. الاسم البديل: `/export`.
- يصدّر `/export-trajectory [path]` ‏[trajectory bundle](/ar/tools/trajectory) بصيغة JSONL للجلسة الحالية. الاسم البديل: `/trajectory`.
- يعرض `/whoami` معرّف المرسل الخاص بك. الاسم البديل: `/id`.
- يصدّر `/export-session [path]` الجلسة الحالية إلى HTML. الاسم المستعار: `/export`.
- يصدّر `/export-trajectory [path]` [حزمة trajectory](/ar/tools/trajectory) بصيغة JSONL للجلسة الحالية. الاسم المستعار: `/trajectory`.
- يعرض `/whoami` معرّف المرسل الخاص بك. الاسم المستعار: `/id`.
- يشغّل `/skill <name> [input]` Skill بالاسم.
- يدير `/allowlist [list|add|remove] ...` إدخالات قائمة السماح. نصي فقط.
- يحل `/approve <id> <decision>` مطالبات موافقة exec.
- يطرح `/btw <question>` سؤالًا جانبيًا من دون تغيير سياق الجلسة في المستقبل. راجع [/tools/btw](/ar/tools/btw).
- يحل `/approve <id> <decision>` طلبات الموافقة على exec.
- يطرح `/btw <question>` سؤالًا جانبيًا دون تغيير سياق الجلسة في المستقبل. راجع [/tools/btw](/ar/tools/btw).
- يدير `/subagents list|kill|log|info|send|steer|spawn` تشغيلات الوكلاء الفرعيين للجلسة الحالية.
- يدير `/acp spawn|cancel|steer|close|sessions|status|set-mode|set|cwd|permissions|timeout|model|reset-options|doctor|install|help` جلسات ACP وخيارات وقت التشغيل.
- يربط `/focus <target>` سلسلة Discord الحالية أو موضوع/محادثة Telegram بهدف جلسة.
- يزيل `/unfocus` الارتباط الحالي.
- يعرض `/agents` الوكلاء المرتبطين بالسلسلة للجلسة الحالية.
- يوقف `/kill <id|#|all>` وكيلًا فرعيًا واحدًا أو جميع الوكلاء الفرعيين الجاري تشغيلهم.
- يرسل `/steer <id|#> <message>` توجيهًا إلى وكيل فرعي قيد التشغيل. الاسم البديل: `/tell`.
- يقرأ `/config show|get|set|unset` أو يكتب `openclaw.json`. للمالك فقط. ويتطلب `commands.config: true`.
- يقرأ `/mcp show|get|set|unset` أو يكتب إعدادات خادم MCP التي يديرها OpenClaw تحت `mcp.servers`. للمالك فقط. ويتطلب `commands.mcp: true`.
- يفحص `/plugins list|inspect|show|get|install|enable|disable` حالة Plugin أو يغيّرها. و`/plugin` اسم بديل. عمليات الكتابة للمالك فقط. ويتطلب `commands.plugins: true`.
- يدير `/debug show|set|unset|reset` تجاوزات الإعدادات الخاصة بوقت التشغيل فقط. للمالك فقط. ويتطلب `commands.debug: true`.
- يتحكم `/usage off|tokens|full|cost` في تذييل الاستخدام لكل استجابة أو يطبع ملخص تكلفة محلي.
- يربط `/focus <target>` خيط Discord الحالي أو موضوع/محادثة Telegram بهدف جلسة.
- يزيل `/unfocus` الربط الحالي.
- يسرد `/agents` الوكلاء المرتبطين بالخيط للجلسة الحالية.
- يوقف `/kill <id|#|all>` وكيلًا فرعيًا واحدًا أو جميع الوكلاء الفرعيين قيد التشغيل.
- يرسل `/steer <id|#> <message>` توجيهًا إلى وكيل فرعي قيد التشغيل. الاسم المستعار: `/tell`.
- يقرأ `/config show|get|set|unset` الملف `openclaw.json` أو يكتبه. للمالك فقط. ويتطلب `commands.config: true`.
- يقرأ `/mcp show|get|set|unset` إعداد خادم MCP الذي يديره OpenClaw تحت `mcp.servers` أو يكتبه. للمالك فقط. ويتطلب `commands.mcp: true`.
- يفحص `/plugins list|inspect|show|get|install|enable|disable` حالة Plugin أو يغيّرها. و`/plugin` اسم مستعار. الكتابة للمالك فقط. ويتطلب `commands.plugins: true`.
- يدير `/debug show|set|unset|reset` تجاوزات الإعداد الخاصة بوقت التشغيل فقط. للمالك فقط. ويتطلب `commands.debug: true`.
- يتحكم `/usage off|tokens|full|cost` في تذييل الاستخدام لكل رد أو يطبع ملخص تكلفة محليًا.
- يتحكم `/tts on|off|status|provider|limit|summary|audio|help` في TTS. راجع [/tools/tts](/ar/tools/tts).
- يعيد `/restart` تشغيل OpenClaw عند التمكين. الافتراضي: مفعّل؛ اضبط `commands.restart: false` لتعطيله.
- يضبط `/activation mention|always` وضع التفعيل في المجموعات.
- يعيد `/restart` تشغيل OpenClaw عندما يكون مفعّلًا. الافتراضي: مفعّل؛ اضبط `commands.restart: false` لتعطيله.
- يضبط `/activation mention|always` وضع التفعيل للمجموعة.
- يضبط `/send on|off|inherit` سياسة الإرسال. للمالك فقط.
- يشغّل `/bash <command>` أمر shell على المضيف. نصي فقط. الاسم البديل: `! <command>`. ويتطلب `commands.bash: true` بالإضافة إلى قوائم سماح `tools.elevated`.
- يتحقق `!poll [sessionId]` من مهمة bash خلفية.
- يوقف `!stop [sessionId]` مهمة bash خلفية.
- يشغّل `/bash <command>` أمر shell على المضيف. نصي فقط. الاسم المستعار: `! <command>`. ويتطلب `commands.bash: true` بالإضافة إلى قوائم سماح `tools.elevated`.
- يفحص `!poll [sessionId]` مهمة bash في الخلفية.
- يوقف `!stop [sessionId]` مهمة bash في الخلفية.
### أوامر dock المولّدة
تُولَّد أوامر Dock من Plugins القنوات التي تدعم الأوامر الأصلية. المجموعة المضمنة الحالية:
تُولَّد أوامر Dock من إضافات القنوات التي تدعم الأوامر الأصلية. المجموعة المجمّعة الحالية:
- `/dock-discord` ‏(الاسم البديل: `/dock_discord`)
- `/dock-mattermost` ‏(الاسم البديل: `/dock_mattermost`)
- `/dock-slack` ‏(الاسم البديل: `/dock_slack`)
- `/dock-telegram` ‏(الاسم البديل: `/dock_telegram`)
- `/dock-discord` (الاسم المستعار: `/dock_discord`)
- `/dock-mattermost` (الاسم المستعار: `/dock_mattermost`)
- `/dock-slack` (الاسم المستعار: `/dock_slack`)
- `/dock-telegram` (الاسم المستعار: `/dock_telegram`)
### أوامر Plugins المضمنة
### أوامر Plugin المجمّعة
يمكن لـ Plugins المضمنة إضافة المزيد من slash commands. الأوامر المضمنة الحالية في هذا المستودع:
يمكن للإضافات المجمّعة إضافة مزيد من أوامر الشرطة المائلة. أوامر الحزم المجمّعة الحالية في هذا المستودع:
- يبدّل `/dreaming [on|off|status|help]` memory dreaming. راجع [Dreaming](/ar/concepts/dreaming).
- يبدّل `/dreaming [on|off|status|help]` Dreaming الذاكرة. راجع [Dreaming](/ar/concepts/dreaming).
- يدير `/pair [qr|status|pending|approve|cleanup|notify]` تدفق اقتران/إعداد الأجهزة. راجع [الاقتران](/ar/channels/pairing).
- يسلّح `/phone status|arm <camera|screen|writes|all> [duration]|disarm` أوامر node عالية الخطورة الخاصة بالهاتف مؤقتًا.
- يدير `/voice status|list [limit]|set <voiceId|name>` إعدادات صوت Talk. وفي Discord يكون اسم الأمر الأصلي هو `/talkvoice`.
- يرسل `/card ...` إعدادات LINE rich card المسبقة. راجع [LINE](/ar/channels/line).
- يفحص `/codex status|models|threads|resume|compact|review|account|mcp|skills` ويضبط Codex app-server harness المضمن. راجع [Codex Harness](/ar/plugins/codex-harness).
- أوامر خاصة بـ QQBot فقط:
- يقوم `/phone status|arm <camera|screen|writes|all> [duration]|disarm` بتسليح أوامر Node الهاتف عالية الخطورة مؤقتًا.
- يدير `/voice status|list [limit]|set <voiceId|name>` إعدادات صوت Talk. في Discord، يكون اسم الأمر الأصلي هو `/talkvoice`.
- يرسل `/card ...` الإعدادات المسبقة للبطاقات الغنية في LINE. راجع [LINE](/ar/channels/line).
- يفحص `/codex status|models|threads|resume|compact|review|account|mcp|skills` ويضبط harness خادم التطبيق Codex المجمّع. راجع [Codex Harness](/ar/plugins/codex-harness).
- أوامر QQBot فقط:
- `/bot-ping`
- `/bot-version`
- `/bot-help`
@ -173,75 +173,76 @@ x-i18n:
### أوامر Skills الديناميكية
تُكشف Skills القابلة للاستدعاء من المستخدم أيضًا كأوامر شرطة مائلة:
تُعرَّض Skills القابلة للاستدعاء من المستخدم أيضًا كأوامر slash:
- يعمل `/skill <name> [input]` دائمًا كنقطة دخول عامة.
- قد تظهر Skills أيضًا كأوامر مباشرة مثل `/prose` عندما تسجلها Skill/Plugin.
- يعمل `/skill <name> [input]` دائمًا كنقطة الدخول العامة.
- قد تظهر Skills أيضًا كأوامر مباشرة مثل `/prose` عندما يقوم الـ Skill/Plugin بتسجيلها.
- يتحكم `commands.nativeSkills` و`channels.<provider>.commands.nativeSkills` في تسجيل أوامر Skills الأصلية.
ملاحظات:
- تقبل الأوامر وجود `:` اختياري بين الأمر والمعاملات (مثل `/think: high`, `/send: on`, `/help:`).
- يقبل `/new <model>` اسمًا بديلًا للنموذج، أو `provider/model`، أو اسم مزوّد (مطابقة تقريبية)؛ وإذا لم توجد مطابقة، يُعامل النص على أنه جسم الرسالة.
- تقبل الأوامر وجود `:` اختياريًا بين الأمر والوسائط (مثل `/think: high` و`/send: on` و`/help:`).
- يقبل `/new <model>` اسمًا مستعارًا للنموذج، أو `provider/model`، أو اسم مزوّد (مطابقة تقريبية)؛ وإذا لم توجد مطابقة، فسيُعامل النص على أنه متن الرسالة.
- للحصول على تفصيل كامل لاستخدام المزوّد، استخدم `openclaw status --usage`.
- يتطلب `/allowlist add|remove` القيمة `commands.config=true` ويحترم `configWrites` الخاصة بالقناة.
- في القنوات متعددة الحسابات، تحترم أيضًا أوامر `/allowlist --account <id>` الموجهة للإعدادات و`/config set channels.<provider>.accounts.<id>...` قيمة `configWrites` الخاصة بالحساب الهدف.
- يتحكم `/usage` في تذييل الاستخدام لكل استجابة؛ ويطبع `/usage cost` ملخص تكلفة محليًا من سجلات جلسات OpenClaw.
- في القنوات متعددة الحسابات، تحترم أيضًا الأوامر `/allowlist --account <id>` الموجّهة للإعداد و`/config set channels.<provider>.accounts.<id>...` قيمة `configWrites` الخاصة بالحساب المستهدف.
- يتحكم `/usage` في تذييل الاستخدام لكل رد؛ بينما يطبع `/usage cost` ملخص تكلفة محليًا من سجلات جلسات OpenClaw.
- يكون `/restart` مفعّلًا افتراضيًا؛ اضبط `commands.restart: false` لتعطيله.
- يقبل `/plugins install <spec>` مواصفات Plugin نفسها التي يقبلها `openclaw plugins install`: مسار/أرشيف محلي، أو حزمة npm، أو `clawhub:<pkg>`.
- يحدّث `/plugins enable|disable` إعدادات Plugin وقد يطلب إعادة تشغيل.
- أمر أصلي خاص بـ Discord فقط: يتحكم `/vc join|leave|status` في القنوات الصوتية (ويتطلب `channels.discord.voice` والأوامر الأصلية؛ وليس متاحًا كنص).
- تتطلب أوامر ربط السلاسل في Discord (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`) أن تكون thread bindings الفعلية مفعّلة (`session.threadBindings.enabled` و/أو `channels.discord.threadBindings.enabled`).
- مرجع أوامر ACP وسلوك وقت التشغيل: [ACP Agents](/ar/tools/acp-agents).
- الغرض من `/verbose` هو التصحيح وزيادة الرؤية؛ اتركه **معطّلًا** في الاستخدام العادي.
- يُعد `/trace` أضيق من `/verbose`: فهو يكشف فقط أسطر التتبع/التصحيح المملوكة لـ Plugin ويبقي ضوضاء الأدوات المطولة العادية معطلة.
- يؤدي `/fast on|off` إلى استمرار تجاوز على مستوى الجلسة. استخدم خيار `inherit` في واجهة الجلسات لمسحه والعودة إلى الإعدادات الافتراضية من الإعدادات.
- يُعد `/fast` خاصًا بالمزوّد: حيث تربطه OpenAI/OpenAI Codex بالقيمة `service_tier=priority` على نقاط نهاية Responses الأصلية، بينما تربطه طلبات Anthropic العامة المباشرة، بما في ذلك الحركة الموثقة عبر OAuth المرسلة إلى `api.anthropic.com`, بالقيمة `service_tier=auto` أو `standard_only`. راجع [OpenAI](/ar/providers/openai) و[Anthropic](/ar/providers/anthropic).
- لا تزال ملخصات فشل الأدوات تُعرض عند اللزوم، لكن نص الفشل التفصيلي لا يُضمَّن إلا عندما تكون `/verbose` على `on` أو `full`.
- تُعد `/reasoning` و`/verbose` و`/trace` محفوفة بالمخاطر في إعدادات المجموعات: فقد تكشف عن استدلال داخلي، أو مخرجات أدوات، أو تشخيصات Plugin لم تكن تنوي كشفها. يُفضّل تركها معطلة، خاصة في الدردشات الجماعية.
- يؤدي `/model` إلى استمرار نموذج الجلسة الجديد فورًا.
- إذا كان الوكيل في وضع الخمول، فسيستخدم التشغيل التالي هذا النموذج مباشرةً.
- إذا كان هناك تشغيل نشط بالفعل، يضع OpenClaw التبديل المباشر كحالة معلّقة ولا يعيد التشغيل إلى النموذج الجديد إلا عند نقطة إعادة محاولة نظيفة.
- إذا كان نشاط الأداة أو خرج الرد قد بدأ بالفعل، فقد يظل التبديل المعلّق في الطابور حتى فرصة إعادة محاولة لاحقة أو دور المستخدم التالي.
- **المسار السريع:** تُعالَج الرسائل التي تحتوي على أوامر فقط من المرسلين المدرجين في قائمة السماح فورًا (تتجاوز الطابور + النموذج).
- **تقييد الإشارات في المجموعات:** تتجاوز الرسائل التي تحتوي على أوامر فقط من المرسلين المدرجين في قائمة السماح متطلبات الإشارة.
- **الاختصارات المضمّنة (للمرسلين المدرجين في قائمة السماح فقط):** تعمل بعض الأوامر أيضًا عند تضمينها داخل رسالة عادية وتُزال قبل أن يرى النموذج النص المتبقي.
- مثال: تؤدي `hey /status` إلى تشغيل رد حالة، ويستمر النص المتبقي عبر التدفق العادي.
- حاليًا: `/help`, `/commands`, `/status`, `/whoami` ‏(`/id`).
- يتم تجاهل الرسائل التي تحتوي على أوامر فقط من غير المصرّح لهم بصمت، وتُعامل الرموز المضمّنة `/...` كنص عادي.
- **أوامر Skills:** تُكشف Skills ‏`user-invocable` كأوامر شرطة مائلة. وتُطهَّر الأسماء إلى `a-z0-9_` ‏(بحد أقصى 32 محرفًا)؛ وتحصل التصادمات على لاحقات رقمية (مثل `_2`).
- يشغّل `/skill <name> [input]` Skill بالاسم (ويكون مفيدًا عندما تمنع حدود الأوامر الأصلية إنشاء أمر لكل Skill).
- افتراضيًا، تُمرّر أوامر Skills إلى النموذج كطلب عادي.
- يمكن لـ Skills أن تعلن اختياريًا `command-dispatch: tool` لتوجيه الأمر مباشرةً إلى أداة (حتمي، من دون نموذج).
- مثال: `/prose` ‏(Plugin ‏OpenProse) — راجع [OpenProse](/ar/prose).
- **وسائط الأوامر الأصلية:** يستخدم Discord الإكمال التلقائي للخيارات الديناميكية (وقوائم الأزرار عندما تُهمل المعاملات المطلوبة). أما Telegram وSlack فيعرضان قائمة أزرار عندما يدعم الأمر خيارات وتُهمل الوسيط.
- يقوم `/plugins enable|disable` بتحديث إعداد Plugin وقد يطالب بإعادة تشغيل.
- أمر أصلي خاص بـ Discord فقط: يتحكم `/vc join|leave|status` في القنوات الصوتية (يتطلب `channels.discord.voice` والأوامر الأصلية؛ وغير متاح كنص).
- تتطلب أوامر ربط الخيوط في Discord (`/focus` و`/unfocus` و`/agents` و`/session idle` و`/session max-age`) تفعيل ربط الخيوط الفعلي (`session.threadBindings.enabled` و/أو `channels.discord.threadBindings.enabled`).
- مرجع أوامر ACP وسلوك وقت التشغيل: [وكلاء ACP](/ar/tools/acp-agents).
- الغرض من `/verbose` هو التصحيح وزيادة الوضوح؛ أبقه **معطّلًا** في الاستخدام العادي.
- `/trace` أضيق نطاقًا من `/verbose`: فهو يكشف فقط أسطر التتبع/التصحيح المملوكة لـ Plugin ويُبقي ضجيج الأدوات العادي في الوضع المطوّل معطّلًا.
- يستمر `/fast on|off` كتجاوز على مستوى الجلسة. استخدم خيار `inherit` في واجهة Sessions لمسحه والعودة إلى إعدادات config الافتراضية.
- يكون `/fast` خاصًا بالمزوّد: حيث يربطه OpenAI/OpenAI Codex مع `service_tier=priority` على نقاط نهاية Responses الأصلية، بينما تربطه طلبات Anthropic العامة المباشرة، بما في ذلك الحركة الموثقة عبر OAuth المرسلة إلى `api.anthropic.com`، مع `service_tier=auto` أو `standard_only`. راجع [OpenAI](/ar/providers/openai) و[Anthropic](/ar/providers/anthropic).
- لا تزال ملخصات إخفاق الأدوات تُعرض عند الاقتضاء، لكن نص الإخفاق المفصل لا يُضمَّن إلا عندما يكون `/verbose` على `on` أو `full`.
- تُعد `/reasoning` و`/verbose` و`/trace` محفوفة بالمخاطر في إعدادات المجموعات: فقد تكشف عن الاستدلال الداخلي، أو مخرجات الأدوات، أو تشخيصات Plugin التي لم تكن تقصد كشفها. ومن الأفضل إبقاؤها معطلة، خصوصًا في دردشات المجموعات.
- يحفظ `/model` نموذج الجلسة الجديد فورًا.
- إذا كان الوكيل في وضع الخمول، فسيستخدمه التشغيل التالي مباشرة.
- إذا كان هناك تشغيل نشط بالفعل، يضع OpenClaw تبديلًا مباشرًا معلّقًا ولا يعيد التشغيل إلى النموذج الجديد إلا عند نقطة إعادة محاولة نظيفة.
- إذا كان نشاط الأداة أو مخرجات الرد قد بدأت بالفعل، فقد يظل التبديل المعلق في قائمة الانتظار حتى فرصة إعادة محاولة لاحقة أو دور المستخدم التالي.
- **المسار السريع:** تُعالج الرسائل التي تحتوي على أوامر فقط من المرسلين المدرجين في قائمة السماح فورًا (تتجاوز قائمة الانتظار + النموذج).
- **تقييد الإشارة في المجموعات:** تتجاوز الرسائل التي تحتوي على أوامر فقط من المرسلين المدرجين في قائمة السماح متطلبات الإشارة.
- **الاختصارات المضمّنة (للمرسلين المدرجين في قائمة السماح فقط):** تعمل بعض الأوامر أيضًا عندما تكون مضمنة في رسالة عادية وتُزال قبل أن يرى النموذج النص المتبقي.
- مثال: يؤدي `hey /status` إلى رد بالحالة، ويستمر النص المتبقي عبر التدفق العادي.
- حاليًا: `/help` و`/commands` و`/status` و`/whoami` (`/id`).
- تُتجاهل الرسائل التي تحتوي على أوامر فقط من غير المصرّح لهم بصمت، وتُعامل رموز `/...` المضمّنة كنص عادي.
- **أوامر Skills:** تُعرَض Skills التي تحمل `user-invocable` كأوامر slash. وتُنظَّف الأسماء إلى `a-z0-9_` (بحد أقصى 32 حرفًا)؛ وتحصل التصادمات على لواحق رقمية (مثل `_2`).
- يشغّل `/skill <name> [input]` Skill بالاسم (وهو مفيد عندما تمنع حدود الأوامر الأصلية وجود أوامر لكل Skill).
- افتراضيًا، تُمرر أوامر Skills إلى النموذج كطلب عادي.
- يمكن لـ Skills اختياريًا إعلان `command-dispatch: tool` لتوجيه الأمر مباشرة إلى أداة (حتمي، دون نموذج).
- مثال: `/prose` (Plugin OpenProse) — راجع [OpenProse](/ar/prose).
- **وسائط الأوامر الأصلية:** يستخدم Discord الإكمال التلقائي للخيارات الديناميكية (وقوائم الأزرار عندما تحذف الوسائط المطلوبة). ويعرض Telegram وSlack قائمة أزرار عندما يدعم الأمر اختيارات وتُسقط الوسيطة.
## `/tools`
تجيب `/tools` عن سؤال وقت تشغيل، وليس سؤال إعدادات: **ما الذي يمكن لهذا الوكيل استخدامه الآن
يجيب `/tools` عن سؤال وقت تشغيل، لا عن سؤال إعداد: **ما الذي يمكن لهذا الوكيل استخدامه الآن
في هذه المحادثة**.
- تكون `/tools` الافتراضية مختصرة ومهيأة للمسح السريع.
- تضيف `/tools verbose` أوصافًا قصيرة.
- تكشف أسطح الأوامر الأصلية التي تدعم الوسائط عن مفتاح الوضع نفسه `compact|verbose`.
- تكون النتائج محددة النطاق بالجلسة، لذا فإن تغيير الوكيل، أو القناة، أو السلسلة، أو تفويض المرسل، أو النموذج يمكن
أن يغير الخرج.
- تتضمن `/tools` الأدوات التي يمكن الوصول إليها فعليًا في وقت التشغيل، بما في ذلك الأدوات الأساسية، و
أدوات Plugin المتصلة، والأدوات المملوكة للقنوات.
- يكون `/tools` الافتراضي موجزًا ومهيأً للمسح السريع.
- يضيف `/tools verbose` أوصافًا قصيرة.
- تكشف الأسطح ذات الأوامر الأصلية التي تدعم الوسائط عن مفتاح الوضع نفسه بوصفه `compact|verbose`.
- تكون النتائج ضمن نطاق الجلسة، لذلك قد يؤدي تغيير الوكيل أو القناة أو الخيط أو تخويل المرسل أو النموذج إلى
تغيير المخرجات.
- يتضمن `/tools` الأدوات التي يمكن الوصول إليها فعليًا وقت التشغيل، بما في ذلك الأدوات الأساسية، والأدوات المتصلة
المملوكة لـ Plugin، والأدوات المملوكة للقنوات.
وبالنسبة إلى تحرير الملفات التعريفية والتجاوزات، استخدم لوحة Tools في واجهة التحكم أو أسطح الإعدادات/الفهارس بدلًا
من معاملة `/tools` كفهرس ثابت.
لتحرير ملفات التعريف والتجاوزات، استخدم لوحة Tools في Control UI أو أسطح config/catalog بدلًا
من التعامل مع `/tools` على أنه فهرس ثابت.
## أسطح الاستخدام (ما الذي يظهر وأين)
- **استخدام المزوّد/الحصة** (مثل: “Claude 80% left”) يظهر في `/status` بالنسبة إلى مزوّد النموذج الحالي عندما يكون تتبع الاستخدام مفعّلًا. ويطبع OpenClaw نوافذ المزوّدين إلى `% left`؛ وبالنسبة إلى MiniMax، يتم عكس حقول النسبة المئوية المعتمدة على المتبقي فقط قبل العرض، وتفضّل استجابات `model_remains` إدخال نموذج الدردشة مع تسمية خطة موسومة بالنموذج.
- يمكن لأسطر **الرموز/التخزين المؤقت** في `/status` أن تعود إلى أحدث إدخال استخدام في النص عندما تكون لقطة الجلسة الحية قليلة المعلومات. ولا تزال القيم الحية غير الصفرية الموجودة تفوز، كما يمكن للاحتياط من النص أن يستعيد أيضًا تسمية النموذج النشط في وقت التشغيل بالإضافة إلى مجموع أكبر موجّه إلى prompt عندما تكون المجاميع المخزنة مفقودة أو أصغر.
- يتم التحكم في **الرموز/التكلفة لكل استجابة** عبر `/usage off|tokens|full` ‏(تُضاف إلى الردود العادية).
- **استخدام/حصة المزوّد** (مثال: “Claude 80% left”) يظهر في `/status` لمزوّد النموذج الحالي عندما يكون تتبع الاستخدام مفعّلًا. ويطبّع OpenClaw نوافذ المزوّدين إلى `% left`؛ وبالنسبة إلى MiniMax، تُعكس حقول النسبة المئوية التي تحتوي على المتبقي فقط قبل العرض، كما أن استجابات `model_remains` تفضّل إدخال نموذج الدردشة بالإضافة إلى تسمية الخطة الموسومة بالنموذج.
- قد تعود **أسطر الرمز/التخزين المؤقت** في `/status` إلى أحدث إدخال استخدام في النص عندما تكون لقطة الجلسة الحية فقيرة. وتظل القيم الحية غير الصفرية القائمة هي الفائزة، كما يمكن أن يستعيد الرجوع إلى النص أيضًا تسمية نموذج وقت التشغيل النشط بالإضافة إلى إجمالي أكبر موجه إلى prompt عندما تكون الإجماليات المخزنة مفقودة أو أصغر.
- **وقت التشغيل مقابل المشغّل:** يبلّغ `/status` عن `Runtime` لمسار التنفيذ الفعلي وحالة sandbox، وعن `Runner` للجهة التي تشغّل الجلسة فعليًا: Pi المضمن، أو مزود مدعوم بـ CLI، أو harness/backend خاص بـ ACP.
- يتم التحكم في **الرموز/التكلفة لكل رد** بواسطة `/usage off|tokens|full` (تُلحق بالردود العادية).
- يتعلق `/model status` بـ **النماذج/المصادقة/نقاط النهاية**، وليس بالاستخدام.
## اختيار النموذج (`/model`)
يُنفّذ `/model` كتوجيه.
يُنفَّذ `/model` كتوجيه.
أمثلة:
@ -256,14 +257,14 @@ x-i18n:
ملاحظات:
- يعرض `/model` و`/model list` منتقيًا مضغوطًا ومرقّمًا (عائلة النموذج + المزوّدون المتاحون).
- في Discord، يفتح `/model` و`/models` منتقيًا تفاعليًا يحتوي على قوائم منسدلة للمزوّد والنموذج بالإضافة إلى خطوة Submit.
- يختار `/model <#>` من ذلك المنتقي (ويفضّل المزوّد الحالي عندما يكون ذلك ممكنًا).
- يعرض `/model status` العرض التفصيلي، بما في ذلك نقطة نهاية المزوّد المضبوطة (`baseUrl`) ووضع API ‏(`api`) عند التوفر.
- يعرض `/model` و`/model list` منتقيًا موجزًا مرقّمًا (عائلة النموذج + المزوّدات المتاحة).
- في Discord، يفتح `/model` و`/models` منتقيًا تفاعليًا مع قوائم منسدلة للمزوّد والنموذج بالإضافة إلى خطوة Submit.
- يختار `/model <#>` من ذلك المنتقي (ويفضّل المزوّد الحالي عندما يكون ممكنًا).
- يعرض `/model status` العرض التفصيلي، بما في ذلك نقطة نهاية المزوّد المُعدّة (`baseUrl`) ووضع API (`api`) عند توفرهما.
## تجاوزات التصحيح
يسمح لك `/debug` بضبط تجاوزات إعدادات **وقت تشغيل فقط** (في الذاكرة، وليس على القرص). للمالك فقط. وهو معطل افتراضيًا؛ فعّله باستخدام `commands.debug: true`.
يتيح `/debug` ضبط تجاوزات config **خاصة بوقت التشغيل فقط** (في الذاكرة، وليس على القرص). للمالك فقط. وهو معطّل افتراضيًا؛ قم بتمكينه باستخدام `commands.debug: true`.
أمثلة:
@ -277,12 +278,12 @@ x-i18n:
ملاحظات:
- تُطبّق التجاوزات فورًا على قراءات الإعدادات الجديدة، لكنها **لا** تكتب إلى `openclaw.json`.
- استخدم `/debug reset` لمسح جميع التجاوزات والعودة إلى الإعدادات الموجودة على القرص.
- تُطبّق التجاوزات فورًا على قراءات config الجديدة، لكنها لا تكتب إلى `openclaw.json`.
- استخدم `/debug reset` لمسح كل التجاوزات والعودة إلى config الموجود على القرص.
## خرج تتبع Plugin
## مخرجات تتبع Plugin
يسمح لك `/trace` بتبديل **أسطر تتبع/تصحيح Plugins ذات النطاق الخاص بالجلسة** من دون تشغيل الوضع المطول الكامل.
يتيح لك `/trace` تبديل **أسطر تتبع/تصحيح Plugin ضمن نطاق الجلسة** دون تشغيل الوضع المطوّل الكامل.
أمثلة:
@ -294,16 +295,16 @@ x-i18n:
ملاحظات:
- يعرض `/trace` من دون وسيط حالة التتبع الحالية للجلسة.
- يؤدي `/trace on` إلى تفعيل أسطر تتبع Plugin للجلسة الحالية.
- يؤدي `/trace off` إلى تعطيلها مرة أخرى.
- يمكن أن تظهر أسطر تتبع Plugin في `/status` وكإرسالة تشخيص متابعة بعد رد المساعد العادي.
- لا يحل `/trace` محل `/debug`؛ إذ لا يزال `/debug` يدير تجاوزات الإعدادات الخاصة بوقت التشغيل فقط.
- لا يحل `/trace` محل `/verbose`؛ إذ يظل خرج الأدوات/الحالة المطول العادي تابعًا لـ `/verbose`.
- يعرض `/trace` دون وسيطة حالة التتبع الحالية للجلسة.
- يفعّل `/trace on` أسطر تتبع Plugin للجلسة الحالية.
- يعطّلها `/trace off` مرة أخرى.
- يمكن أن تظهر أسطر تتبع Plugin في `/status` وكـ رسالة تشخيصية لاحقة بعد رد المساعد العادي.
- لا يستبدل `/trace` الأمر `/debug`؛ إذ يظل `/debug` مسؤولًا عن تجاوزات config الخاصة بوقت التشغيل فقط.
- لا يستبدل `/trace` الأمر `/verbose`؛ إذ تظل مخرجات الأدوات/الحالة العادية في الوضع المطوّل تابعة لـ `/verbose`.
## تحديثات الإعدادات
## تحديثات الإعداد
يكتب `/config` إلى الإعدادات الموجودة على القرص (`openclaw.json`). للمالك فقط. وهو معطل افتراضيًا؛ فعّله باستخدام `commands.config: true`.
يكتب `/config` إلى config الموجود على القرص (`openclaw.json`). للمالك فقط. وهو معطّل افتراضيًا؛ قم بتمكينه باستخدام `commands.config: true`.
أمثلة:
@ -317,12 +318,12 @@ x-i18n:
ملاحظات:
- يتم التحقق من الإعدادات قبل الكتابة؛ وتُرفض التغييرات غير الصالحة.
- تستمر تحديثات `/config` بعد إعادة التشغيل.
- يتم التحقق من صحة config قبل الكتابة؛ وتُرفض التغييرات غير الصالحة.
- تستمر تحديثات `/config` عبر عمليات إعادة التشغيل.
## تحديثات MCP
يكتب `/mcp` تعريفات خوادم MCP التي يديرها OpenClaw تحت `mcp.servers`. للمالك فقط. وهو معطل افتراضيًا؛ فعّله باستخدام `commands.mcp: true`.
يكتب `/mcp` تعريفات خادم MCP التي يديرها OpenClaw تحت `mcp.servers`. للمالك فقط. وهو معطّل افتراضيًا؛ قم بتمكينه باستخدام `commands.mcp: true`.
أمثلة:
@ -335,12 +336,12 @@ x-i18n:
ملاحظات:
- يخزّن `/mcp` الإعدادات في إعدادات OpenClaw، وليس في إعدادات المشروع التي يملكها Pi.
- تقرر محولات وقت التشغيل أي وسائل نقل تكون قابلة للتنفيذ فعليًا.
- يخزن `/mcp` config في إعداد OpenClaw، وليس في إعدادات المشروع المملوكة لـ Pi.
- تحدد محولات وقت التشغيل وسائل النقل القابلة للتنفيذ فعليًا.
## تحديثات Plugins
## تحديثات Plugin
يسمح `/plugins` للمشغّلين بفحص Plugins المكتشفة وتبديل التمكين في الإعدادات. ويمكن للتدفقات المخصصة للقراءة فقط استخدام `/plugin` كاسم بديل. وهو معطل افتراضيًا؛ فعّله باستخدام `commands.plugins: true`.
يتيح `/plugins` للمشغلين فحص الإضافات المكتشفة وتبديل حالة التمكين في config. ويمكن لتدفقات القراءة فقط استخدام `/plugin` كاسم مستعار. وهو معطّل افتراضيًا؛ قم بتمكينه باستخدام `commands.plugins: true`.
أمثلة:
@ -354,28 +355,28 @@ x-i18n:
ملاحظات:
- يستخدم `/plugins list` و`/plugins show` اكتشاف Plugin الحقيقي مقابل مساحة العمل الحالية بالإضافة إلى الإعدادات الموجودة على القرص.
- يحدّث `/plugins enable|disable` إعدادات Plugin فقط؛ ولا يثبت أو يزيل Plugins.
- بعد تغييرات التمكين/التعطيل، أعد تشغيل gateway لتطبيقها.
- يستخدم `/plugins list` و`/plugins show` اكتشاف Plugin حقيقيًا مقابل مساحة العمل الحالية بالإضافة إلى config الموجود على القرص.
- يقوم `/plugins enable|disable` بتحديث config الخاص بـ Plugin فقط؛ ولا يثبت أو يزيل تثبيت الإضافات.
- بعد تغييرات التمكين/التعطيل، أعد تشغيل Gateway لتطبيقها.
## ملاحظات السطح
- **الأوامر النصية** تعمل داخل جلسة الدردشة العادية (تشارك الرسائل الخاصة `main`، وللمجموعات جلساتها الخاصة).
- **الأوامر الأصلية** تستخدم جلسات معزولة:
- تعمل **الأوامر النصية** في جلسة الدردشة العادية (تشارك الرسائل المباشرة `main`، وتمتلك المجموعات جلستها الخاصة).
- تستخدم **الأوامر الأصلية** جلسات معزولة:
- Discord: ‏`agent:<agentId>:discord:slash:<userId>`
- Slack: ‏`agent:<agentId>:slack:slash:<userId>` ‏(يمكن ضبط البادئة عبر `channels.slack.slashCommand.sessionPrefix`)
- Telegram: ‏`telegram:slash:<userId>` ‏(يستهدف جلسة الدردشة عبر `CommandTargetSessionKey`)
- يستهدف **`/stop`** جلسة الدردشة النشطة بحيث يمكنه إيقاف التشغيل الحالي.
- **Slack:** لا يزال `channels.slack.slashCommand` مدعومًا لأمر واحد على نمط `/openclaw`. إذا فعّلت `commands.native`، فيجب عليك إنشاء أمر شرطة مائلة واحد في Slack لكل أمر مضمن (بالأسماء نفسها مثل `/help`). تُسلَّم قوائم وسائط الأوامر الخاصة بـ Slack كأزرار Block Kit مؤقتة.
- استثناء Slack الأصلي: سجّل `/agentstatus` ‏(وليس `/status`) لأن Slack يحجز `/status`. ولا يزال `/status` النصي يعمل في رسائل Slack.
- Slack: ‏`agent:<agentId>:slack:slash:<userId>` (يمكن ضبط البادئة عبر `channels.slack.slashCommand.sessionPrefix`)
- Telegram: ‏`telegram:slash:<userId>` (يستهدف جلسة الدردشة عبر `CommandTargetSessionKey`)
- يستهدف **`/stop`** جلسة الدردشة النشطة حتى يتمكن من إيقاف التشغيل الحالي.
- **Slack:** لا يزال `channels.slack.slashCommand` مدعومًا لأمر واحد على نمط `/openclaw`. وإذا فعّلت `commands.native`، فيجب إنشاء أمر slash واحد في Slack لكل أمر مضمّن (بالأسماء نفسها مثل `/help`). وتُسلَّم قوائم وسائط الأوامر في Slack كأزرار Block Kit مؤقتة.
- استثناء Slack الأصلي: سجّل `/agentstatus` (وليس `/status`) لأن Slack يحتفظ بـ `/status`. ولا يزال `/status` النصي يعمل في رسائل Slack.
## أسئلة BTW الجانبية
يُعد `/btw` **سؤالًا جانبيًا** سريعًا حول الجلسة الحالية.
يمثل `/btw` **سؤالًا جانبيًا** سريعًا حول الجلسة الحالية.
وعلى عكس الدردشة العادية:
- فإنه يستخدم الجلسة الحالية كسياق خلفي،
- فهو يستخدم الجلسة الحالية كسياق خلفي،
- ويعمل كاستدعاء منفصل **من دون أدوات** لمرة واحدة،
- ولا يغيّر سياق الجلسة المستقبلي،
- ولا يُكتب في سجل النص،
@ -390,5 +391,5 @@ x-i18n:
/btw what are we doing right now?
```
راجع [أسئلة BTW الجانبية](/ar/tools/btw) لمعرفة السلوك الكامل وتفاصيل
تجربة المستخدم في العميل.
راجع [أسئلة BTW الجانبية](/ar/tools/btw) للحصول على السلوك الكامل وتفاصيل
تجربة العميل.

168
docs/ar/tools/thinking.md
View File

@ -1,111 +1,111 @@
---
read_when:
- تعديل التفكير أو وضع fast أو تحليل توجيهات verbose أو قيمها الافتراضية
summary: صياغة التوجيهات لأوامر `/think` و`/fast` و`/verbose` و`/trace` وظهور reasoning
- ضبط التفكير، أو وضع السرعة، أو تحليل التوجيه verbose أو القيم الافتراضية الخاصة به
summary: بنية التوجيه لأوامر `/think` و`/fast` و`/verbose` و`/trace` وظهور الاستدلال
title: مستويات التفكير
x-i18n:
generated_at: "2026-04-23T07:34:21Z"
generated_at: "2026-04-23T14:03:34Z"
model: gpt-5.4
provider: openai
source_hash: 66033bb9272c9b9ea8fc85dc91e33e95ce4c469c56a8cd10c19632a5aa8a2338
source_hash: 4efe899f7b47244745a105583b3239effa7975fadd06bd7bcad6327afcc91207
source_path: tools/thinking.md
workflow: 15
---
# مستويات التفكير (توجيهات `/think`)
# مستويات التفكير (`/think` directives)
## ما الذي تفعله
## ما الذي يفعله
- توجيه مضمّن داخل أي متن وارد: `/t <level>` أو `/think:<level>` أو `/thinking <level>`.
- المستويات (والأسماء المستعارة): `off | minimal | low | medium | high | xhigh | adaptive | max`
- minimal → "think"
- low → "think hard"
- medium → "think harder"
- high → "ultrathink" (الحد الأقصى للميزانية)
- xhigh → "ultrathink+" (لنماذج GPT-5.2 + Codex ومستوى الجهد في Anthropic Claude Opus 4.7)
- adaptive → تفكير تكيفي يديره المزوّد (مدعوم لـ Claude 4.6 على Anthropic/Bedrock وAnthropic Claude Opus 4.7)
- max → reasoning بأقصى درجة لدى المزوّد (حاليًا Anthropic Claude Opus 4.7)
- تُطابق `x-high` و`x_high` و`extra-high` و`extra high` و`extra_high` القيمة `xhigh`.
- تُطابق `highest` القيمة `high`.
- ملاحظات المزوّد:
- تستند قوائم ومستخرجات التفكير إلى ملف تعريف المزوّد. وتعلن Plugins الخاصة بالمزوّد مجموعة المستويات الدقيقة للنموذج المحدد، بما في ذلك تسميات مثل `on` الثنائية.
- لا يتم الإعلان عن `adaptive` و`xhigh` و`max` إلا لملفات تعريف المزوّد/النموذج التي تدعمها. وتُرفض التوجيهات المكتوبة للمستويات غير المدعومة مع إظهار الخيارات الصحيحة لذلك النموذج.
- تُعاد مطابقة المستويات غير المدعومة المخزنة سابقًا حسب رتبة ملف تعريف المزوّد. تعود `adaptive` إلى `medium` في النماذج غير التكيفية، بينما تعود `xhigh` و`max` إلى أعلى مستوى مدعوم غير `off` للنموذج المحدد.
- تستخدم نماذج Anthropic Claude 4.6 افتراضيًا القيمة `adaptive` عندما لا يتم ضبط مستوى thinking صريح.
- لا يستخدم Anthropic Claude Opus 4.7 التفكير التكيفي افتراضيًا. ويظل الجهد الافتراضي في API مملوكًا للمزوّد ما لم تضبط مستوى thinking صريحًا.
- يطابق Anthropic Claude Opus 4.7 الأمر `/think xhigh` مع التفكير التكيفي إضافة إلى `output_config.effort: "xhigh"`، لأن `/think` هو توجيه thinking و`xhigh` هو إعداد الجهد في Opus 4.7.
- كما يكشف Anthropic Claude Opus 4.7 أيضًا عن `/think max`؛ وهو يطابق مسار أقصى جهد مملوك للمزوّد نفسه.
- تطابق نماذج OpenAI GPT الأمر `/think` عبر دعم `reasoning.effort` الخاص بـ Responses API حسب النموذج. ويرسل `/think off` القيمة `reasoning.effort: "none"` فقط عندما يدعمها النموذج المستهدف؛ وإلا يحذف OpenClaw حمولة تعطيل reasoning بدلًا من إرسال قيمة غير مدعومة.
- تستخدم MiniMax (`minimax/*`) على مسار البث المتوافق مع Anthropic افتراضيًا `thinking: { type: "disabled" }` ما لم تضبط thinking صراحةً في params الخاصة بالنموذج أو الطلب. وهذا يتجنب تسرّب دلتا `reasoning_content` من صيغة بث Anthropic غير الأصلية لدى MiniMax.
- تدعم Z.AI (`zai/*`) فقط التفكير الثنائي (`on`/`off`). ويُعامل أي مستوى غير `off` على أنه `on` (ويُطابق `low`).
- تطابق Moonshot (`moonshot/*`) الأمر `/think off` مع `thinking: { type: "disabled" }`، وأي مستوى غير `off` مع `thinking: { type: "enabled" }`. وعندما يكون التفكير مفعّلًا، لا تقبل Moonshot إلا `tool_choice` من النوع `auto|none`؛ ويقوم OpenClaw بتطبيع القيم غير المتوافقة إلى `auto`.
- توجيه مضمّن داخل أي نص وارد: `/t <level>` أو `/think:<level>` أو `/thinking <level>`.
- المستويات (الأسماء المستعارة): `off | minimal | low | medium | high | xhigh | adaptive | max`
- minimal ← “think”
- low ← “think hard”
- medium ← “think harder”
- high ← “ultrathink” (الحد الأقصى للميزانية)
- xhigh ← “ultrathink+” (جهد GPT-5.2 + نماذج Codex وAnthropic Claude Opus 4.7)
- adaptive ← التفكير التكيفي المُدار من Provider (مدعوم لـ Claude 4.6 على Anthropic/Bedrock وAnthropic Claude Opus 4.7)
- max ← أقصى استدلال لدى Provider (حاليًا Anthropic Claude Opus 4.7)
- يتم تعيين `x-high` و`x_high` و`extra-high` و`extra high` و`extra_high` إلى `xhigh`.
- يتم تعيين `highest` إلى `high`.
- ملاحظات خاصة بالـ Provider:
- تُدار قوائم ومنتقيات التفكير بواسطة ملفات تعريف Provider. وتصرّح Plugins الخاصة بالـ Provider بمجموعة المستويات الدقيقة للنموذج المحدد، بما في ذلك تسميات مثل `on` الثنائية.
- لا يتم الإعلان عن `adaptive` و`xhigh` و`max` إلا لملفات تعريف Provider/النموذج التي تدعمها. وتُرفض التوجيهات المكتوبة لمستويات غير مدعومة مع عرض الخيارات الصالحة لذلك النموذج.
- تُعاد تسوية المستويات غير المدعومة المخزنة مسبقًا حسب رتبة ملف تعريف Provider. ويرجع `adaptive` إلى `medium` على النماذج غير التكيفية، بينما يرجع `xhigh` و`max` إلى أعلى مستوى مدعوم غير `off` للنموذج المحدد.
- تستخدم نماذج Anthropic Claude 4.6 افتراضيًا `adaptive` عندما لا يكون هناك مستوى تفكير صريح معيّن.
- لا يستخدم Anthropic Claude Opus 4.7 التفكير التكيفي افتراضيًا. وتظل القيمة الافتراضية لجهد API مملوكة للـ Provider ما لم تعيّن مستوى تفكير صريحًا.
- يربط Anthropic Claude Opus 4.7 ‏`/think xhigh` بالتفكير التكيفي مع `output_config.effort: "xhigh"`، لأن `/think` هو توجيه تفكير و`xhigh` هو إعداد الجهد في Opus 4.7.
- يوفّر Anthropic Claude Opus 4.7 أيضًا `/think max`؛ وهو يُربط بالمسار نفسه لأقصى جهد مملوك للـ Provider.
- تربط نماذج OpenAI GPT ‏`/think` عبر دعم Responses API الخاص بالجهد حسب النموذج. ويرسل `/think off` القيمة `reasoning.effort: "none"` فقط عندما يدعمها النموذج الهدف؛ وإلا فإن OpenClaw يحذف حمولة تعطيل الاستدلال بدلًا من إرسال قيمة غير مدعومة.
- يستخدم MiniMax ‏(`minimax/*`) على مسار البث المتوافق مع Anthropic افتراضيًا `thinking: { type: "disabled" }` ما لم تعيّن التفكير صراحةً في params الخاصة بالنموذج أو params الخاصة بالطلب. ويمنع هذا تسرب فروق `reasoning_content` من تنسيق بث Anthropic غير الأصلي لدى MiniMax.
- يدعم Z.AI ‏(`zai/*`) التفكير الثنائي فقط (`on`/`off`). ويُعامل أي مستوى غير `off` على أنه `on` (ويُربط بـ `low`).
- يربط Moonshot ‏(`moonshot/*`) الأمر `/think off` إلى `thinking: { type: "disabled" }` وأي مستوى غير `off` إلى `thinking: { type: "enabled" }`. وعندما يكون التفكير مفعّلًا، لا يقبل Moonshot إلا `tool_choice` بالقيم `auto|none`؛ ويقوم OpenClaw بتسوية القيم غير المتوافقة إلى `auto`.
## ترتيب الحسم
1. التوجيه المضمّن داخل الرسالة (يُطبّق على تلك الرسالة فقط).
1. التوجيه المضمّن في الرسالة (ينطبق على تلك الرسالة فقط).
2. تجاوز الجلسة (يُضبط بإرسال رسالة تحتوي على التوجيه فقط).
3. الافتراضي لكل وكيل (`agents.list[].thinkingDefault` في التهيئة).
4. الافتراضي العام (`agents.defaults.thinkingDefault` في التهيئة).
5. الرجوع الاحتياطي: الافتراضي المعلن من المزوّد عند التوفر، و`low` لبقية نماذج الكتالوج المعلَّمة بأنها قادرة على reasoning، و`off` خلاف ذلك.
3. الافتراضي لكل وكيل (`agents.list[].thinkingDefault` في التكوين).
4. الافتراضي العام (`agents.defaults.thinkingDefault` في التكوين).
5. الرجوع: القيمة الافتراضية المصرّح بها من Provider عند توفرها؛ وإلا فإن النماذج القادرة على الاستدلال تُحسم إلى `medium` أو أقرب مستوى مدعوم غير `off` لذلك النموذج، بينما تظل النماذج غير الاستدلالية على `off`.
## ضبط افتراضي للجلسة
## تعيين افتراضي للجلسة
- أرسل رسالة تكون **فقط** التوجيه (مع السماح بالمسافات)، مثل `/think:medium` أو `/t high`.
- يظل ذلك مثبتًا للجلسة الحالية (لكل مرسل افتراضيًا)؛ ويُزال بواسطة `/think:off` أو إعادة تعيين خمول الجلسة.
- يتم إرسال رد تأكيد (`Thinking level set to high.` / `Thinking disabled.`). وإذا كان المستوى غير صالح (مثل `/thinking big`)، يُرفض الأمر مع تلميح وتبقى حالة الجلسة من دون تغيير.
- أرسل `/think` (أو `/think:`) من دون وسيطة لرؤية مستوى التفكير الحالي.
- أرسل رسالة تكون **فقط** هي التوجيه (مع السماح بالمسافات)، مثل `/think:medium` أو `/t high`.
- يظل هذا ثابتًا للجلسة الحالية (لكل مرسل افتراضيًا)؛ ويُمسح بواسطة `/think:off` أو بإعادة تعيين خمول الجلسة.
- يتم إرسال رد تأكيد (`Thinking level set to high.` / `Thinking disabled.`). وإذا كان المستوى غير صالح (مثل `/thinking big`) فسيُرفض الأمر مع تلميح وتبقى حالة الجلسة دون تغيير.
- أرسل `/think` (أو `/think:`) بدون وسيطة لمعرفة مستوى التفكير الحالي.
## التطبيق بحسب الوكيل
## التطبيق حسب الوكيل
- **Embedded Pi**: يتم تمرير المستوى المحسوم إلى وقت تشغيل Pi المضمّن داخل العملية.
- **Pi المضمّن**: يتم تمرير المستوى المحسوم إلى وقت تشغيل وكيل Pi داخل العملية.
## وضع Fast (`/fast`)
## وضع السرعة (`/fast`)
- المستويات: `on|off`.
- تبدّل الرسالة التي تحتوي فقط على التوجيه تجاوز fast-mode للجلسة وترد بـ `Fast mode enabled.` / `Fast mode disabled.`.
- أرسل `/fast` (أو `/fast status`) من دون وضع لرؤية حالة fast-mode الفعلية الحالية.
- يحسم OpenClaw وضع fast بهذا الترتيب:
1. التوجيه المضمّن/الخاص بالرسالة فقط `/fast on|off`
- تؤدي الرسالة التي تحتوي على التوجيه فقط إلى تبديل تجاوز وضع السرعة في الجلسة والرد بـ `Fast mode enabled.` / `Fast mode disabled.`.
- أرسل `/fast` (أو `/fast status`) بدون وضع لمعرفة حالة وضع السرعة الفعلية الحالية.
- يحسم OpenClaw وضع السرعة بهذا الترتيب:
1. ‏`/fast on|off` المضمّن/التوجيه فقط
2. تجاوز الجلسة
3. الافتراضي لكل وكيل (`agents.list[].fastModeDefault`)
4. تهيئة كل نموذج: `agents.defaults.models["<provider>/<model>"].params.fastMode`
5. الرجوع الاحتياطي: `off`
- بالنسبة إلى `openai/*`، يطابق وضع fast المعالجة ذات الأولوية في OpenAI بإرسال `service_tier=priority` على طلبات Responses المدعومة.
- بالنسبة إلى `openai-codex/*`، يرسل وضع fast الإشارة نفسها `service_tier=priority` على Codex Responses. ويحافظ OpenClaw على مفتاح `/fast` مشترك واحد عبر مساري المصادقة.
- بالنسبة إلى طلبات `anthropic/*` العامة المباشرة، بما في ذلك الحركة المرسلة بمصادقة OAuth إلى `api.anthropic.com`، يطابق وضع fast مستويات خدمة Anthropic: يؤدي `/fast on` إلى ضبط `service_tier=auto`، ويؤدي `/fast off` إلى ضبط `service_tier=standard_only`.
4. تكوين كل نموذج: `agents.defaults.models["<provider>/<model>"].params.fastMode`
5. الرجوع: `off`
- بالنسبة إلى `openai/*`، يُربط وضع السرعة بمعالجة OpenAI ذات الأولوية عبر إرسال `service_tier=priority` في طلبات Responses المدعومة.
- بالنسبة إلى `openai-codex/*`، يرسل وضع السرعة علم `service_tier=priority` نفسه على Codex Responses. ويحافظ OpenClaw على مفتاح `/fast` مشترك واحد عبر مساري المصادقة كليهما.
- بالنسبة إلى طلبات `anthropic/*` العامة المباشرة، بما في ذلك الحركة الموثقة عبر OAuth المرسلة إلى `api.anthropic.com`، يُربط وضع السرعة بطبقات خدمة Anthropic: يؤدي `/fast on` إلى تعيين `service_tier=auto`، ويؤدي `/fast off` إلى تعيين `service_tier=standard_only`.
- بالنسبة إلى `minimax/*` على المسار المتوافق مع Anthropic، يعيد `/fast on` (أو `params.fastMode: true`) كتابة `MiniMax-M2.7` إلى `MiniMax-M2.7-highspeed`.
- تتقدم params الصريحة `serviceTier` / `service_tier` الخاصة بـ Anthropic على القيمة الافتراضية لوضع fast عندما يتم ضبط الاثنين معًا. ومع ذلك، لا يزال OpenClaw يتخطى حقن مستوى الخدمة الخاص بـ Anthropic لعناوين URL الأساسية غير التابعة لـ Anthropic.
- يعرض `/status` القيمة `Fast` فقط عندما يكون وضع fast مفعّلًا.
- تتجاوز params الصريحة لـ Anthropic ‏`serviceTier` / `service_tier` الافتراضي الخاص بوضع السرعة عند تعيين كليهما. وما يزال OpenClaw يتجاوز حقن طبقة خدمة Anthropic لعناوين base URL الوكيلة غير التابعة لـ Anthropic.
- يعرض `/status` كلمة `Fast` فقط عندما يكون وضع السرعة مفعّلًا.
## توجيهات Verbose (`/verbose` أو `/v`)
## توجيهات verbose ‏(`/verbose` أو `/v`)
- المستويات: `on` (حد أدنى) | `full` | `off` (الافتراضي).
- تبدّل الرسالة التي تحتوي فقط على التوجيه verbose الخاصة بالجلسة وترد بـ `Verbose logging enabled.` / `Verbose logging disabled.`؛ وتعيد المستويات غير الصالحة تلميحًا من دون تغيير الحالة.
- يخزن `/verbose off` تجاوزًا صريحًا للجلسة؛ ويمكنك مسحه عبر واجهة Sessions UI باختيار `inherit`.
- يؤثر التوجيه المضمّن فقط في تلك الرسالة؛ وتُطبق الافتراضيات على مستوى الجلسة/العالمية في غير ذلك.
- أرسل `/verbose` (أو `/verbose:`) من دون وسيطة لرؤية مستوى verbose الحالي.
- عندما تكون verbose مفعّلة، ترسل الوكلاء التي تصدر نتائج أدوات منظّمة (Pi، ووكلاء JSON الآخرون) كل استدعاء أداة مرة أخرى كرسالة مستقلة للبيانات الوصفية فقط، وتبدأ بـ `<emoji> <tool-name>: <arg>` عندما يكون ذلك متاحًا (المسار/الأمر). وتُرسل هذه الملخصات الخاصة بالأدوات بمجرد بدء كل أداة (فقاعات منفصلة)، وليس كتدفّقات delta.
- تظل ملخصات إخفاق الأدوات مرئية في الوضع العادي، لكن لواحق تفاصيل الأخطاء الخام تُخفى ما لم تكن verbose مساوية لـ `on` أو `full`.
- عندما تكون verbose مساوية لـ `full`، تُمرر أيضًا مخرجات الأدوات بعد الاكتمال (فقاعة منفصلة، مقطوعة إلى طول آمن). وإذا بدّلت `/verbose on|full|off` أثناء تشغيل جارٍ، فإن فقاعات الأدوات اللاحقة ستحترم الإعداد الجديد.
- تؤدي الرسالة التي تحتوي على التوجيه فقط إلى تبديل verbose للجلسة والرد بـ `Verbose logging enabled.` / `Verbose logging disabled.`؛ وتعيد المستويات غير الصالحة تلميحًا من دون تغيير الحالة.
- يؤدي `/verbose off` إلى تخزين تجاوز صريح للجلسة؛ ويمكن مسحه عبر واجهة الجلسات باختيار `inherit`.
- يؤثر التوجيه المضمّن في تلك الرسالة فقط؛ وإلا فتُطبّق افتراضيات الجلسة/العامة.
- أرسل `/verbose` (أو `/verbose:`) بدون وسيطة لمعرفة مستوى verbose الحالي.
- عندما يكون verbose مفعّلًا، فإن الوكلاء الذين يخرجون نتائج أدوات مهيكلة (Pi، ووكلاء JSON الآخرون) يعيدون إرسال كل استدعاء أداة كرسالة مستقلة خاصة بالبيانات التعريفية فقط، مع بادئة `<emoji> <tool-name>: <arg>` عند توفرها (المسار/الأمر). تُرسل ملخصات الأدوات هذه فور بدء كل أداة (فقاعات منفصلة)، وليس كبث فروق.
- تظل ملخصات فشل الأدوات مرئية في الوضع العادي، لكن لاحقات تفاصيل الأخطاء الخام تُخفى ما لم يكن verbose هو `on` أو `full`.
- عندما يكون verbose هو `full`، تُمرر أيضًا مخرجات الأدوات بعد اكتمالها (فقاعة منفصلة، مع اقتطاع إلى طول آمن). وإذا بدّلت `/verbose on|full|off` أثناء وجود تشغيل جارٍ، فستحترم فقاعات الأدوات اللاحقة الإعداد الجديد.
## توجيهات تتبع Plugin (`/trace`)
## توجيهات تتبع Plugin ‏(`/trace`)
- المستويات: `on` | `off` (الافتراضي).
- تبدّل الرسالة التي تحتوي فقط على التوجيه مخرجات تتبع Plugin الخاصة بالجلسة وترد بـ `Plugin trace enabled.` / `Plugin trace disabled.`.
- يؤثر التوجيه المضمّن فقط في تلك الرسالة؛ وتُطبق الافتراضيات على مستوى الجلسة/العالمية في غير ذلك.
- أرسل `/trace` (أو `/trace:`) من دون وسيطة لرؤية مستوى التتبع الحالي.
- يُعد `/trace` أضيق من `/verbose`: فهو يكشف فقط عن أسطر trace/debug المملوكة لـ Plugin مثل ملخصات debug الخاصة بـ Active Memory.
- يمكن أن تظهر أسطر التتبع في `/status` وكـ رسالة تشخيص متابعة بعد رد المساعد العادي.
- تؤدي الرسالة التي تحتوي على التوجيه فقط إلى تبديل مخرجات تتبع Plugin للجلسة والرد بـ `Plugin trace enabled.` / `Plugin trace disabled.`.
- يؤثر التوجيه المضمّن في تلك الرسالة فقط؛ وإلا فتُطبّق افتراضيات الجلسة/العامة.
- أرسل `/trace` (أو `/trace:`) بدون وسيطة لمعرفة مستوى التتبع الحالي.
- يُعد `/trace` أضيق من `/verbose`: فهو يكشف فقط أسطر التتبع/التصحيح المملوكة للـ Plugin مثل ملخصات تصحيح Active Memory.
- قد تظهر أسطر التتبع في `/status` وكَرسالة تشخيصية لاحقة بعد رد المساعد العادي.
## ظهور Reasoning (`/reasoning`)
## ظهور الاستدلال (`/reasoning`)
- المستويات: `on|off|stream`.
- تبدّل الرسالة التي تحتوي فقط على التوجيه ما إذا كانت كتل التفكير ستُعرض في الردود.
- عند التمكين، تُرسل reasoning كـ **رسالة منفصلة** تبدأ بـ `Reasoning:`.
- `stream` (Telegram فقط): يبث reasoning داخل فقاعة المسودة في Telegram أثناء توليد الرد، ثم يرسل الإجابة النهائية من دون reasoning.
- تؤدي الرسالة التي تحتوي على التوجيه فقط إلى تبديل ما إذا كانت كتل التفكير ستُعرض في الردود.
- عند التمكين، يُرسل الاستدلال كـ **رسالة منفصلة** مسبوقة بـ `Reasoning:`.
- `stream` ‏(Telegram فقط): يبث الاستدلال داخل فقاعة مسودة Telegram أثناء إنشاء الرد، ثم يرسل الإجابة النهائية من دون الاستدلال.
- الاسم المستعار: `/reason`.
- أرسل `/reasoning` (أو `/reasoning:`) من دون وسيطة لرؤية مستوى reasoning الحالي.
- ترتيب الحسم: التوجيه المضمّن، ثم تجاوز الجلسة، ثم الافتراضي لكل وكيل (`agents.list[].reasoningDefault`)، ثم الرجوع الاحتياطي (`off`).
- أرسل `/reasoning` (أو `/reasoning:`) بدون وسيطة لمعرفة مستوى الاستدلال الحالي.
- ترتيب الحسم: التوجيه المضمّن، ثم تجاوز الجلسة، ثم الافتراضي لكل وكيل (`agents.list[].reasoningDefault`)، ثم الرجوع (`off`).
## ذو صلة
@ -113,20 +113,20 @@ x-i18n:
## Heartbeats
- يكون متن Heartbeat probe هو prompt الخاصة بـ heartbeat المهيأة (الافتراضي: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`). وتُطبق التوجيهات المضمّنة في رسالة heartbeat كالمعتاد (لكن تجنب تغيير افتراضيات الجلسة من heartbeats).
- يستخدم تسليم Heartbeat افتراضيًا الحمولة النهائية فقط. ولإرسال الرسالة المنفصلة `Reasoning:` أيضًا (عند التوفر)، اضبط `agents.defaults.heartbeat.includeReasoning: true` أو `agents.list[].heartbeat.includeReasoning: true` لكل وكيل.
- نص فحص Heartbeat هو prompt الخاص بـ Heartbeat المكوَّن (الافتراضي: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`). وتُطبَّق التوجيهات المضمّنة في رسالة Heartbeat كالمعتاد (لكن تجنب تغيير افتراضيات الجلسة من رسائل Heartbeat).
- يستخدم تسليم Heartbeat افتراضيًا الحمولة النهائية فقط. ولإرسال رسالة `Reasoning:` المنفصلة أيضًا (عند توفرها)، عيّن `agents.defaults.heartbeat.includeReasoning: true` أو لكل وكيل `agents.list[].heartbeat.includeReasoning: true`.
## واجهة دردشة الويب
- يعكس محدد thinking في دردشة الويب المستوى المخزن للجلسة من مخزن/تهيئة الجلسة الواردة عند تحميل الصفحة.
- يؤدي اختيار مستوى آخر إلى كتابة تجاوز الجلسة فورًا عبر `sessions.patch`؛ ولا ينتظر الإرسال التالي كما أنه ليس تجاوز `thinkingOnce` لمرة واحدة.
- يكون الخيار الأول دائمًا `Default (<resolved level>)`، حيث تأتي القيمة الافتراضية المحسومة من ملف تعريف thinking الخاص بالمزوّد للنموذج النشط في الجلسة.
- يستخدم المحدد `thinkingOptions` التي يعيدها صف جلسة gateway. ولا تحتفظ واجهة المتصفح بقائمة regex خاصة بها للمزوّدات؛ إذ تمتلك Plugins مجموعات المستويات الخاصة بكل نموذج.
- لا يزال `/think:<level>` يعمل ويحدّث مستوى الجلسة المخزن نفسه، لذلك تظل توجيهات الدردشة والمحدد متزامنين.
- يعكس منتقي التفكير في دردشة الويب المستوى المخزن للجلسة من مخزن/تكوين الجلسة الواردة عند تحميل الصفحة.
- يؤدي اختيار مستوى آخر إلى كتابة تجاوز الجلسة فورًا عبر `sessions.patch`؛ ولا ينتظر الإرسال التالي وليس تجاوزًا لمرة واحدة `thinkingOnce`.
- يكون الخيار الأول دائمًا `Default (<resolved level>)`، حيث تأتي القيمة الافتراضية المحسومة من ملف تعريف التفكير الخاص بـ Provider للنموذج النشط في الجلسة إضافةً إلى منطق الرجوع نفسه الذي يستخدمه `/status` و`session_status`.
- يستخدم المنتقي `thinkingOptions` المُعادة من صف جلسة Gateway. ولا تحتفظ واجهة المتصفح بقائمة Regex خاصة بها للـ Provider؛ إذ تمتلك Plugins مجموعات المستويات الخاصة بالنموذج.
- ما يزال `/think:<level>` يعمل ويحدّث مستوى الجلسة المخزن نفسه، بحيث تظل توجيهات الدردشة والمنتقي متزامنين.
## ملفات تعريف المزوّد
## ملفات تعريف Provider
- يمكن لـ Plugins الخاصة بالمزوّد كشف `resolveThinkingProfile(ctx)` لتعريف المستويات الافتراضية والمدعومة للنموذج.
- يملك كل مستوى في ملف التعريف `id` أساسيًا مخزنًا (`off` أو `minimal` أو `low` أو `medium` أو `high` أو `xhigh` أو `adaptive` أو `max`) ويمكن أن يتضمن `label` للعرض. وتستخدم المزوّدات الثنائية `{ id: "low", label: "on" }`.
- تظل الخطافات القديمة المنشورة (`supportsXHighThinking` و`isBinaryThinking` و`resolveDefaultThinkingLevel`) موجودة كمحوّلات توافق، لكن مجموعات المستويات المخصصة الجديدة يجب أن تستخدم `resolveThinkingProfile`.
- تكشف صفوف Gateway عن `thinkingOptions` و`thinkingDefault` بحيث تعرض عملاء ACP/chat ملف التعريف نفسه الذي يستخدمه التحقق وقت التشغيل.
- يمكن لـ Plugins الخاصة بالـ Provider كشف `resolveThinkingProfile(ctx)` لتعريف المستويات الافتراضية والمدعومة للنموذج.
- يحتوي كل مستوى في الملف التعريفي على `id` أساسي مخزن (`off` أو `minimal` أو `low` أو `medium` أو `high` أو `xhigh` أو `adaptive` أو `max`) وقد يتضمن `label` للعرض. وتستخدم Providers الثنائية `{ id: "low", label: "on" }`.
- تظل hooks القديمة المنشورة (`supportsXHighThinking` و`isBinaryThinking` و`resolveDefaultThinkingLevel`) موجودة كمهايئات توافق، لكن مجموعات المستويات المخصصة الجديدة يجب أن تستخدم `resolveThinkingProfile`.
- تكشف صفوف Gateway القيمتين `thinkingOptions` و`thinkingDefault` بحيث تعرض عملاء ACP/الدردشة ملف التعريف نفسه الذي يستخدمه تحقق وقت التشغيل.

371
docs/ar/web/control-ui.md
View File

@ -1,26 +1,26 @@
---
read_when:
- أنت تريد تشغيل Gateway من متصفح الانترنت
- أنت تريد وصول tailnet من دون أنفاق SSH
summary: واجهة Control UI معتمدة على المتصفح لـ Gateway ‏(الدردشة، وNode، والتكوين)
- تريد تشغيل Gateway من المتصفح
- تريد الوصول عبر Tailnet من دون أنفاق SSH
summary: واجهة Control UI المستندة إلى المتصفح لـ Gateway (الدردشة، وNode، والتكوين)
title: Control UI
x-i18n:
generated_at: "2026-04-23T07:34:59Z"
generated_at: "2026-04-23T14:03:34Z"
model: gpt-5.4
provider: openai
source_hash: 05bed9a917878d4849eb7502952e27b7c7a3bf848223735d513d545d51baef6d
source_hash: ce0ed08db83a04d47122c5ada0507d6a9e4c725f8ad4fa8f62cb5d4f0412bfc6
source_path: web/control-ui.md
workflow: 15
---
# Control UI (المتصفح)
إن Control UI هو تطبيق صفحة واحدة صغير مبني باستخدام **Vite + Lit** ويُقدَّم من خلال Gateway:
Control UI هي تطبيق صفحة واحدة صغير مبني باستخدام **Vite + Lit** ويقدّمه Gateway:
- الافتراضي: `http://<host>:18789/`
- بادئة اختيارية: اضبط `gateway.controlUi.basePath` (مثل `/openclaw`)
وهو يتحدث **مباشرة إلى Gateway WebSocket** على المنفذ نفسه.
ويتحدث **مباشرةً إلى Gateway WebSocket** على المنفذ نفسه.
## فتح سريع (محلي)
@ -28,163 +28,156 @@ x-i18n:
- [http://127.0.0.1:18789/](http://127.0.0.1:18789/) (أو [http://localhost:18789/](http://localhost:18789/))
إذا فشل تحميل الصفحة، فابدأ Gateway أولًا: `openclaw gateway`.
إذا تعذر تحميل الصفحة، فابدأ Gateway أولًا: `openclaw gateway`.
تُمرَّر المصادقة أثناء مصافحة WebSocket عبر:
تُزوَّد المصادقة أثناء مصافحة WebSocket عبر:
- `connect.params.auth.token`
- `connect.params.auth.password`
- رؤوس هوية Tailscale Serve عندما تكون `gateway.auth.allowTailscale: true`
- رؤوس هوية trusted-proxy عندما تكون `gateway.auth.mode: "trusted-proxy"`
- ترويسات هوية Tailscale Serve عندما تكون `gateway.auth.allowTailscale: true`
- ترويسات هوية trusted-proxy عندما يكون `gateway.auth.mode: "trusted-proxy"`
تحتفظ لوحة إعدادات dashboard برمز token للجلسة الحالية في تبويب المتصفح
ولعنوان URL الخاص بـ gateway المحدد؛ ولا يتم حفظ كلمات المرور. عادةً ما ينشئ onboarding
رمز gateway لمصادقة السر المشترك عند أول اتصال، لكن مصادقة password
تعمل أيضًا عندما تكون `gateway.auth.mode` مساوية لـ `"password"`.
تحتفظ لوحة إعدادات لوحة المعلومات برمز مميز لجلسة علامة التبويب الحالية في
المتصفح وبعنوان URL الخاص بـ Gateway المحدد؛ ولا تُحفَظ كلمات المرور. ينشئ
الإعداد الأولي عادةً رمز Gateway للمصادقة بالسر المشترك عند أول اتصال، لكن
المصادقة بكلمة المرور تعمل أيضًا عندما تكون `gateway.auth.mode` مساوية لـ `"password"`.
## اقتران الجهاز (أول اتصال)
## إقران الجهاز (الاتصال الأول)
عند الاتصال بـ Control UI من متصفح أو جهاز جديد، يتطلب Gateway
**موافقة اقتران لمرة واحدة** — حتى لو كنت على Tailnet نفسه
عندما تتصل بـ Control UI من متصفح أو جهاز جديد، فإن Gateway
يتطلب **موافقة إقران لمرة واحدة** — حتى لو كنت على Tailnet نفسها
مع `gateway.auth.allowTailscale: true`. هذا إجراء أمني لمنع
الوصول غير المصرح به.
**ما الذي ستراه:** ‏"disconnected (1008): pairing required"
**ما الذي ستراه:** `"disconnected (1008): pairing required"`
**للموافقة على الجهاز:**
```bash
# سرد الطلبات المعلقة
# List pending requests
openclaw devices list
# الموافقة حسب معرّف الطلب
# Approve by request ID
openclaw devices approve <requestId>
```
إذا أعاد المتصفح محاولة الاقتران مع تفاصيل مصادقة متغيرة (role/scopes/public
key)، فيتم استبدال الطلب المعلق السابق ويُنشأ `requestId` جديد.
إذا أعاد المتصفح محاولة الإقران مع تفاصيل مصادقة متغيرة (الدور/النطاقات/المفتاح
العام)، فسيُستبدل الطلب المعلق السابق ويُنشأ `requestId` جديد.
أعد تشغيل `openclaw devices list` قبل الموافقة.
إذا كان المتصفح مقترنًا بالفعل ثم غيّرته من وصول القراءة إلى
وصول الكتابة/الإدارة، فسيُعامل ذلك على أنه ترقية موافقة، وليس إعادة
اتصال صامتة. يحتفظ OpenClaw بالموافقة القديمة نشطة، ويحظر إعادة الاتصال الأوسع،
ويطلب منك الموافقة على مجموعة النطاقات الجديدة صراحةً.
إذا كان المتصفح مقترنًا بالفعل ثم غيّرته من وصول للقراءة إلى
وصول للكتابة/الإدارة، فسيُعامل هذا على أنه ترقية موافقة، وليس
إعادة اتصال صامتة. يحتفظ OpenClaw بالموافقة القديمة نشطة، ويمنع إعادة الاتصال
الأوسع، ويطلب منك الموافقة على مجموعة النطاقات الجديدة صراحةً.
وبمجرد الموافقة، يتم تذكر الجهاز ولن يحتاج إلى إعادة موافقة إلا
إذا ألغيتَه باستخدام `openclaw devices revoke --device <id> --role <role>`. راجع
[Devices CLI](/ar/cli/devices) لمعرفة تدوير الرموز وإلغائها.
بمجرد الموافقة، يُتذكر الجهاز ولن يتطلب إعادة الموافقة ما لم
تقم بإلغائه باستخدام `openclaw devices revoke --device <id> --role <role>`. راجع
[Devices CLI](/ar/cli/devices) لتدوير الرموز والإلغاء.
**ملاحظات:**
- تتم الموافقة تلقائيًا على اتصالات المتصفح المحلية المباشرة عبر loopback ‏(`127.0.0.1` / `localhost`).
- لا تزال اتصالات المتصفح عبر tailnet وLAN تتطلب موافقة صريحة، حتى عندما
- اتصالات المتصفح المحلية المباشرة عبر local loopback (`127.0.0.1` / `localhost`) تُعتمَد
تلقائيًا.
- لا تزال اتصالات المتصفح عبر Tailnet وLAN تتطلب موافقة صريحة، حتى عندما
تصدر من الجهاز نفسه.
- يولّد كل ملف تعريف للمتصفح معرّف جهاز فريدًا، لذا فإن تبديل المتصفحات أو
مسح بيانات المتصفح سيتطلب إعادة الاقتران.
- يولّد كل ملف تعريف متصفح معرّف جهاز فريدًا، لذلك فإن تبديل المتصفحات أو
مسح بيانات المتصفح سيتطلب إعادة الإقران.
## الهوية الشخصية (محلية للمتصفح)
## الهوية الشخصية (محلية في المتصفح)
تدعم Control UI هوية شخصية لكل متصفح — اسم عرض وصورة رمزية
يتم إرفاقهما بالرسائل الصادرة لأغراض الإسناد في الجلسات المشتركة. تعيش هذه الهوية في
تخزين المتصفح، وهي مقيّدة بملف تعريف المتصفح الحالي،
ولا تغادر مضيف gateway ما لم تُرسلها صراحةً مع طلب.
تدعم Control UI هوية شخصية لكل متصفح (اسم عرض وصورة رمزية)
تُرفق بالرسائل الصادرة لأغراض الإسناد في الجلسات المشتركة. وتعيش في تخزين
المتصفح، وتكون محصورة بملف تعريف المتصفح الحالي، ولا تُزامَن مع الأجهزة الأخرى
ولا تُحفَظ من جهة الخادم إلا ضمن بيانات تأليف النصوص العادية
للرسائل التي ترسلها فعليًا. يؤدي مسح بيانات الموقع أو تبديل المتصفحات إلى
إعادة تعيينها إلى فارغة.
- الهوية **محلية للمتصفح فقط**. لا تتم مزامنتها مع الأجهزة الأخرى وليست
جزءًا من ملف تكوين gateway.
- يؤدي مسح بيانات الموقع أو تبديل المتصفحات إلى إعادة تعيين الهوية إلى
فراغ؛ ولا تحاول Control UI إعادة بنائها من حالة الخادم.
- لا يُحفَظ أي شيء يتعلق بالهوية الشخصية على جانب الخادم باستثناء
بيانات إسناد transcript العادية الخاصة بالرسائل التي ترسلها فعلًا.
## نقطة نهاية التكوين وقت التشغيل
## نقطة نهاية تكوين وقت التشغيل
تجلب Control UI إعدادات وقت التشغيل الخاصة بها من
`/__openclaw/control-ui-config.json`. وتُقيَّد نقطة النهاية تلك بالمصادقة نفسها
الخاصة بـ gateway مثل بقية سطح HTTP: لا تستطيع المتصفحات غير
المصادق عليها جلبها، ويتطلب الجلب الناجح إما token/password صالحًا بالفعل لـ gateway،
أو هوية Tailscale Serve، أو هوية trusted-proxy. وهذا يمنع
تسرّب أعلام الميزات وبيانات نقطة النهاية الخاصة بـ Control UI إلى
أدوات الفحص غير المصادق عليها على المضيفين المشتركين.
`/__openclaw/control-ui-config.json`. وتخضع نقطة النهاية هذه لنفس
مصادقة Gateway مثل بقية سطح HTTP: لا تستطيع المتصفحات غير المصادَق عليها
جلبها، ويتطلب الجلب الناجح إما رمز/كلمة مرور Gateway صالحين بالفعل،
أو هوية Tailscale Serve، أو هوية trusted-proxy.
## دعم اللغة
يمكن لـ Control UI أن يترجم نفسه عند أول تحميل بناءً على لغة المتصفح لديك.
ولتجاوز ذلك لاحقًا، افتح **Overview -> Gateway Access -> Language**. يوجد
يمكن لـ Control UI أن تترجم نفسها عند أول تحميل استنادًا إلى لغة
متصفحك المحلية. ولتجاوز ذلك لاحقًا، افتح **Overview -> Gateway Access -> Language**. يوجد
منتقي اللغة في بطاقة Gateway Access، وليس تحت Appearance.
- اللغات المدعومة: `en`, `zh-CN`, `zh-TW`, `pt-BR`, `de`, `es`, `ja-JP`, `ko`, `fr`, `tr`, `uk`, `id`, `pl`, `th`
- يتم تحميل الترجمات غير الإنجليزية بكسل داخل المتصفح.
- تُحفَظ اللغة المحددة في تخزين المتصفح ويُعاد استخدامها في الزيارات اللاحقة.
- ترجع مفاتيح الترجمة المفقودة إلى الإنجليزية.
- اللغات المحلية المدعومة: `en`، `zh-CN`، `zh-TW`، `pt-BR`، `de`، `es`، `ja-JP`، `ko`، `fr`، `tr`، `uk`، `id`، `pl`، `th`
- تُحمَّل الترجمات غير الإنجليزية بتحميل كسول في المتصفح.
- تُحفَظ اللغة المحددة في تخزين المتصفح ويُعاد استخدامها في الزيارات المستقبلية.
- تعود مفاتيح الترجمة المفقودة إلى الإنجليزية.
## ما الذي يمكنه فعله (اليوم)
## ما الذي يمكنه فعله (حاليًا)
- الدردشة مع النموذج عبر Gateway WS ‏(`chat.history`, `chat.send`, `chat.abort`, `chat.inject`)
- بث استدعاءات الأدوات + بطاقات مخرجات الأدوات الحية في Chat ‏(أحداث الوكيل)
- القنوات: حالة القنوات المضمّنة والمضمّنة/الخارجية الخاصة بالـ Plugins، وتسجيل دخول QR، وتكوين لكل قناة (`channels.status`, `web.login.*`, `config.patch`)
- Instances: قائمة الحضور + التحديث (`system-presence`)
- Sessions: سرد + تجاوزات لكل جلسة خاصة بالنموذج/التفكير/الوضع السريع/الوضع المفصل/التتبع/reasoning ‏(`sessions.list`, `sessions.patch`)
- Dreams: حالة Dreaming، ومفتاح التفعيل/التعطيل، وقارئ Dream Diary ‏(`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`)
- مهام Cron: السرد/الإضافة/التعديل/التشغيل/التفعيل/التعطيل + سجل التشغيل (`cron.*`)
- Skills: الحالة، والتفعيل/التعطيل، والتثبيت، وتحديثات مفاتيح API ‏(`skills.*`)
- Nodes: السرد + الإمكانات (`node.list`)
- موافقات Exec: تعديل قوائم السماح الخاصة بـ gateway أو Node + سياسة السؤال الخاصة بـ `exec host=gateway/node` ‏(`exec.approvals.*`)
- التكوين: عرض/تعديل `~/.openclaw/openclaw.json` ‏(`config.get`, `config.set`)
- الدردشة مع النموذج عبر Gateway WS (`chat.history`, `chat.send`, `chat.abort`, `chat.inject`)
- بث استدعاءات الأدوات + بطاقات مخرجات الأدوات المباشرة في Chat (أحداث الوكيل)
- القنوات: حالة القنوات المضمنة بالإضافة إلى قنوات Plugin المضمنة/الخارجية، وتسجيل الدخول عبر QR، وتكوين كل قناة على حدة (`channels.status`, `web.login.*`, `config.patch`)
- Instances: قائمة الوجود + التحديث (`system-presence`)
- الجلسات: قائمة + تجاوزات لكل جلسة للنموذج/التفكير/السريع/المفصل/التتبع/الاستدلال (`sessions.list`, `sessions.patch`)
- Dreams: حالة Dreaming، ومفتاح التمكين/التعطيل، وقارئ Dream Diary (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`)
- مهام Cron: إدراج/إضافة/تحرير/تشغيل/تمكين/تعطيل + سجل التشغيل (`cron.*`)
- Skills: الحالة، التمكين/التعطيل، التثبيت، تحديثات مفاتيح API (`skills.*`)
- Nodes: القائمة + السعات (`node.list`)
- موافقات exec: تحرير قوائم السماح الخاصة بـ Gateway أو Node + سياسة ask لـ `exec host=gateway/node` (`exec.approvals.*`)
- التكوين: عرض/تحرير `~/.openclaw/openclaw.json` (`config.get`, `config.set`)
- التكوين: التطبيق + إعادة التشغيل مع التحقق (`config.apply`) وإيقاظ آخر جلسة نشطة
- تتضمن كتابات التكوين حارس base-hash لمنع الكتابة فوق تعديلات متزامنة
- تقوم كتابات التكوين (`config.set`/`config.apply`/`config.patch`) أيضًا بإجراء تحقق مسبق لحل SecretRef النشط بالنسبة إلى المراجع الموجودة في حمولة التكوين المرسلة؛ وتُرفض المراجع النشطة غير المحلولة قبل الكتابة
- مخطط التكوين + عرض النماذج (`config.schema` / `config.schema.lookup`,
بما في ذلك `title` / `description` الخاصة بالحقول، وتلميحات واجهة المستخدم المطابقة، وملخصات الأبناء المباشرين،
وبيانات المستندات الوصفية على عقد الكائنات/الأحرف البديلة/المصفوفات/التركيب المتداخلة،
بالإضافة إلى مخططات Plugin والقناة عندما تكون متاحة)؛ ويتوفر محرر Raw JSON
فقط عندما تكون اللقطة قادرة على تنفيذ round-trip خام آمن
- إذا تعذر على اللقطة تنفيذ round-trip للنص الخام بأمان، تفرض Control UI وضع Form وتعطل وضع Raw لتلك اللقطة
- يحافظ خيار "Reset to saved" في محرر Raw JSON على الشكل المكتوب خامًا (التنسيق، والتعليقات، وتخطيط `$include`) بدلًا من إعادة عرض لقطة مسطّحة، بحيث تنجو التعديلات الخارجية من إعادة التعيين عندما تكون اللقطة قادرة على تنفيذ round-trip آمن
- تُعرض قيم كائنات Structured SecretRef للقراءة فقط داخل مدخلات النص في النماذج لمنع تلف الكائن إلى string عن طريق الخطأ
- التصحيح: لقطات status/health/models + سجل الأحداث + استدعاءات RPC يدوية (`status`, `health`, `models.list`)
- السجلات: tail مباشر لسجلات ملفات gateway مع التصفية/التصدير (`logs.tail`)
- التحديث: تشغيل تحديث package/git + إعادة التشغيل (`update.run`) مع تقرير إعادة تشغيل
- تتضمن كتابات التكوين حارس base-hash لمنع إتلاف التعديلات المتزامنة
- كتابات التكوين (`config.set`/`config.apply`/`config.patch`) تُجري أيضًا فحصًا مسبقًا لحل SecretRef النشط للمراجع في حمولة التكوين المرسلة؛ وتُرفض المراجع النشطة غير المحلولة الموجودة في الحمولة قبل الكتابة
- مخطط التكوين + عرض النموذج (`config.schema` / `config.schema.lookup`,
بما في ذلك `title` / `description` للحقل، وتلميحات واجهة المستخدم المطابقة، وملخصات الأبناء
المباشرين، وبيانات التوثيق الوصفية لعُقد الكائنات/أحرف البدل/المصفوفات/التركيب المتداخلة،
بالإضافة إلى مخططات Plugin + القنوات عندما تكون متاحة)؛ ولا يكون محرر Raw JSON
متاحًا إلا عندما تحتوي اللقطة على round-trip خام آمن
- إذا تعذر على لقطة ما تنفيذ round-trip للنص الخام بأمان، فإن Control UI تفرض وضع Form وتعطل وضع Raw لتلك اللقطة
- يحافظ خيار "Reset to saved" في محرر Raw JSON على الشكل المكتوب خامًا (التنسيق، والتعليقات، وتخطيط `$include`) بدلًا من إعادة عرض لقطة مسطحة، بحيث تبقى التعديلات الخارجية بعد إعادة التعيين عندما تتمكن اللقطة من تنفيذ round-trip آمن
- تُعرَض قيم كائنات SecretRef المهيكلة للقراءة فقط في مدخلات النص بالنموذج لمنع إفساد الكائنات إلى سلاسل نصية عن طريق الخطأ
- التصحيح: لقطات الحالة/الصحة/النماذج + سجل الأحداث + استدعاءات RPC اليدوية (`status`, `health`, `models.list`)
- السجلات: متابعة مباشرة لسجلات ملفات Gateway مع التصفية/التصدير (`logs.tail`)
- التحديث: تشغيل تحديث حزمة/git + إعادة التشغيل (`update.run`) مع تقرير إعادة التشغيل
ملاحظات لوحة مهام Cron:
- بالنسبة إلى المهام المعزولة، يكون تسليم الملخص المُعلن هو الافتراضي. ويمكنك التبديل إلى none إذا كنت تريد تشغيلات داخلية فقط.
- بالنسبة إلى المهام المعزولة، يكون التسليم افتراضيًا إعلان ملخص. يمكنك التبديل إلى none إذا كنت تريد تشغيلات داخلية فقط.
- تظهر حقول القناة/الهدف عند تحديد announce.
- يستخدم وضع Webhook القيمة `delivery.mode = "webhook"` مع تعيين `delivery.to` إلى عنوان URL صالح لـ HTTP(S) webhook.
- بالنسبة إلى مهام الجلسة الرئيسية، يتوفر وضعا التسليم webhook وnone.
- تتضمن عناصر التحكم المتقدمة في التعديل delete-after-run، ومسح تجاوز الوكيل، وخيارات exact/stagger الخاصة بـ cron،
وتجاوزات agent model/thinking، ومفاتيح best-effort delivery.
- يكون التحقق من النماذج مضمّنًا مع أخطاء على مستوى الحقول؛ وتعطّل القيم غير الصالحة زر الحفظ حتى يتم إصلاحها.
- اضبط `cron.webhookToken` لإرسال bearer token مخصص؛ وإذا تم حذفه، يُرسل webhook من دون رأس مصادقة.
- الرجوع الاحتياطي المهمل: لا تزال المهام القديمة المخزنة مع `notify: true` قادرة على استخدام `cron.webhook` حتى تتم هجرتها.
- يستخدم وضع Webhook القيمة `delivery.mode = "webhook"` مع ضبط `delivery.to` على عنوان URL صالح لـ HTTP(S) Webhook.
- بالنسبة إلى مهام الجلسة الرئيسية، يكون وضعا التسليم webhook وnone متاحين.
- تتضمن عناصر التحكم في التحرير المتقدم delete-after-run، وclear agent override، وخيارات Cron exact/stagger،
وتجاوزات agent model/thinking، ومفاتيح تسليم best-effort.
- يكون التحقق من صحة النموذج مضمّنًا مع أخطاء على مستوى الحقول؛ وتعطّل القيم غير الصالحة زر الحفظ حتى يتم إصلاحها.
- اضبط `cron.webhookToken` لإرسال رمز bearer مخصص؛ وإذا حُذف فسيُرسل Webhook من دون ترويسة مصادقة.
- الرجوع الاحتياطي المتقادم: لا تزال المهام القديمة المخزنة مع `notify: true` تستطيع استخدام `cron.webhook` حتى تتم هجرتها.
## سلوك الدردشة
## سلوك Chat
- إن `chat.send` **غير حاجب**: فهو يقرّ فورًا بـ `{ runId, status: "started" }` ويتم بث الاستجابة عبر أحداث `chat`.
- تؤدي إعادة الإرسال باستخدام `idempotencyKey` نفسه إلى `{ status: "in_flight" }` أثناء التشغيل، وإلى `{ status: "ok" }` بعد الإكمال.
- تكون استجابات `chat.history` مقيّدة بالحجم لأمان واجهة المستخدم. وعندما تكون إدخالات transcript كبيرة جدًا، قد يقوم Gateway باقتطاع حقول النص الطويلة، أو حذف كتل البيانات الوصفية الثقيلة، أو استبدال الرسائل الضخمة بعنصر نائب (`[chat.history omitted: message too large]`).
- كما يقوم `chat.history` أيضًا بإزالة وسوم التوجيه المضمنة المخصّصة للعرض فقط من نص المساعد المرئي (مثل `[[reply_to_*]]` و`[[audio_as_voice]]`)، وحمولات XML الخاصة باستدعاءات الأدوات بالنص العادي (بما في ذلك `<tool_call>...</tool_call>`, `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>`, وكتل استدعاءات الأدوات المبتورة)، ويحذف رموز التحكم بالنموذج المتسربة بنمط ASCII/العرض الكامل، كما يحذف إدخالات المساعد التي يكون نصها المرئي كله هو الرمز الصامت الدقيق `NO_REPLY` / `no_reply`.
- يضيف `chat.inject` ملاحظة مساعد إلى transcript الخاص بالجلسة ويبث حدث `chat` لتحديثات واجهة المستخدم فقط (من دون تشغيل وكيل، ومن دون تسليم إلى القناة).
- تقوم منتقيات النموذج والتفكير في رأس الدردشة بترقيع الجلسة النشطة فورًا عبر `sessions.patch`؛ فهي تجاوزات ثابتة للجلسة وليست خيارات إرسال لدور واحد فقط.
- `chat.send` **غير حاجز**: فهو يؤكد فورًا بالقيمة `{ runId, status: "started" }` ويتدفق الرد عبر أحداث `chat`.
- تؤدي إعادة الإرسال باستخدام `idempotencyKey` نفسه إلى إرجاع `{ status: "in_flight" }` أثناء التشغيل، و`{ status: "ok" }` بعد الاكتمال.
- تكون استجابات `chat.history` محددة الحجم حفاظًا على أمان واجهة المستخدم. عندما تكون إدخالات النص كبيرة جدًا، قد يقوم Gateway باقتطاع حقول النص الطويلة، أو حذف كتل البيانات الوصفية الثقيلة، أو استبدال الرسائل كبيرة الحجم بعنصر نائب (`[chat.history omitted: message too large]`).
- يقوم `chat.history` أيضًا بإزالة وسوم التوجيه المضمنة المعروضة فقط من نص المساعد المرئي (مثل `[[reply_to_*]]` و`[[audio_as_voice]]`)، وحمولات XML النصية الصريحة لاستدعاء الأدوات (بما في ذلك `<tool_call>...</tool_call>`, `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>`, وكتل استدعاء الأدوات المقتطعة)، ورموز التحكم الخاصة بالنموذج المسربة بصيغة ASCII/العرض الكامل، ويحذف إدخالات المساعد التي يكون نصها المرئي بالكامل هو فقط الرمز الصامت المطابق تمامًا `NO_REPLY` / `no_reply`.
- يقوم `chat.inject` بإلحاق ملاحظة مساعد إلى نص الجلسة ويبث حدث `chat` لتحديثات واجهة المستخدم فقط (من دون تشغيل وكيل، ومن دون تسليم عبر القناة).
- يقوم منتقيا النموذج والتفكير في رأس الدردشة بعمل patch للجلسة النشطة فورًا عبر `sessions.patch`؛ وهي تجاوزات ثابتة للجلسة وليست خيارات إرسال لدورة واحدة فقط.
- الإيقاف:
- انقر **Stop** ‏(يستدعي `chat.abort`)
- اكتب `/stop` ‏(أو عبارات الإيقاف المستقلة مثل `stop`, `stop action`, `stop run`, `stop openclaw`, `please stop`) للإيقاف خارج النطاق
- يدعم `chat.abort` الشكل `{ sessionKey }` ‏(من دون `runId`) لإيقاف جميع التشغيلات النشطة لتلك الجلسة
- الاحتفاظ الجزئي عند الإيقاف:
- عند إيقاف تشغيل ما، قد يظل نص المساعد الجزئي معروضًا في واجهة المستخدم
- يحفظ Gateway النص الجزئي المُوقَف الخاص بالمساعد داخل transcript history عندما توجد مخرجات مخزنة مؤقتًا
- تتضمن الإدخالات المحفوظة بيانات وصفية خاصة بالإيقاف حتى تتمكن مستهلكات transcript من التمييز بين المخرجات الجزئية الناتجة عن الإيقاف وبين مخرجات الإكمال العادية
- انقر **Stop** (يستدعي `chat.abort`)
- اكتب `/stop` (أو عبارات الإيقاف المستقلة مثل `stop` أو `stop action` أو `stop run` أو `stop openclaw` أو `please stop`) للإيقاف خارج النطاق
- يدعم `chat.abort` القيمة `{ sessionKey }` (من دون `runId`) لإيقاف جميع التشغيلات النشطة لتلك الجلسة
- الاحتفاظ بالجزئيات عند الإيقاف:
- عندما يتم إيقاف تشغيل ما، يمكن أن يظل نص المساعد الجزئي ظاهرًا في الواجهة
- يحفظ Gateway نص المساعد الجزئي الذي جرى إيقافه في سجل النص عندما توجد مخرجات مخزنة مؤقتًا
- تتضمن الإدخالات المحفوظة بيانات وصفية للإيقاف حتى تتمكن الجهات المستهلكة للنص من التمييز بين الجزئيات الموقوفة ومخرجات الاكتمال العادية
## التضمينات المستضافة
يمكن لرسائل المساعد أن تعرض محتوى ويب مستضافًا مضمنًا باستخدام الرمز المختصر `[embed ...]`.
وتتحكم السياسة الخاصة بصندوق الحماية للـ iframe عبر
`gateway.controlUi.embedSandbox`:
يمكن لرسائل المساعد عرض محتوى ويب مستضاف مضمنًا باستخدام الشيفرة المختصرة `[embed ...]`.
وتتحكم القيمة `gateway.controlUi.embedSandbox` في سياسة iframe sandbox:
- `strict`: يعطّل تنفيذ السكربتات داخل التضمينات المستضافة
- `strict`: يعطل تنفيذ السكربتات داخل التضمينات المستضافة
- `scripts`: يسمح بالتضمينات التفاعلية مع الحفاظ على عزل الأصل؛ وهذا هو
الافتراضي ويكون عادةً كافيًا للألعاب/العناصر التفاعلية ذاتية الاحتواء المعتمدة على المتصفح
- `trusted`: يضيف `allow-same-origin` فوق `allow-scripts` للمستندات من الموقع نفسه
التي تحتاج عمدًا إلى صلاحيات أقوى
الافتراضي ويكون عادةً كافيًا للألعاب/العناصر المصغرة المستقلة
- `trusted`: يضيف `allow-same-origin` فوق `allow-scripts` للمستندات من
الموقع نفسه التي تحتاج عمدًا إلى صلاحيات أقوى
مثال:
@ -198,19 +191,19 @@ key)، فيتم استبدال الطلب المعلق السابق ويُنشأ
}
```
استخدم `trusted` فقط عندما يكون المستند المضمَّن بحاجة فعلية إلى
سلوك same-origin. وبالنسبة إلى معظم الألعاب التي يولدها الوكيل وعناصر canvas التفاعلية، يكون `scripts`
هو الخيار الأكثر أمانًا.
استخدم `trusted` فقط عندما يحتاج المستند المضمّن فعلًا إلى
سلوك same-origin. وبالنسبة إلى معظم الألعاب التي ينشئها الوكيل والعناصر التفاعلية، فإن
`scripts` هو الخيار الأكثر أمانًا.
تظل عناوين URL المطلقة الخارجية للتضمين من نوع `http(s)` محظورة افتراضيًا. وإذا
كنت تريد عمدًا تحميل صفحات خارجية ضمن `[embed url="https://..."]`، فاضبط
تظل عناوين URL المطلقة للتضمين الخارجي `http(s)` محظورة افتراضيًا. وإذا كنت
تريد عمدًا أن يُحمَّل `[embed url="https://..."]` صفحات خارجية، فاضبط
`gateway.controlUi.allowExternalEmbedUrls: true`.
## وصول Tailnet (موصى به)
## الوصول عبر Tailnet (موصى به)
### ‏Tailscale Serve المدمج (المفضل)
### Tailscale Serve المدمج (المفضل)
أبقِ Gateway على loopback ودع Tailscale Serve يعمل كوكيل له عبر HTTPS:
أبقِ Gateway على loopback واجعل Tailscale Serve يمرره عبر HTTPS:
```bash
openclaw gateway --tailscale serve
@ -218,24 +211,24 @@ openclaw gateway --tailscale serve
افتح:
- `https://<magicdns>/` (أو `gateway.controlUi.basePath` الذي قمت بتكوينه)
- `https://<magicdns>/` (أو `gateway.controlUi.basePath` المضبوط لديك)
افتراضيًا، يمكن لطلبات Serve الخاصة بـ Control UI/WebSocket أن تُصادَق عبر رؤوس هوية Tailscale
افتراضيًا، يمكن لمصادقة طلبات Control UI/WebSocket Serve استخدام ترويسات هوية Tailscale
(`tailscale-user-login`) عندما تكون `gateway.auth.allowTailscale` مساوية لـ `true`. يتحقق OpenClaw
من الهوية عبر resolve للعنوان `x-forwarded-for` باستخدام
`tailscale whois` ومطابقته مع الرأس، ولا يقبل هذه القيم إلا عندما
تصل الطلبات إلى loopback مع رؤوس `x-forwarded-*` الخاصة بـ Tailscale. اضبط
`gateway.auth.allowTailscale: false` إذا كنت تريد اشتراط بيانات اعتماد صريحة ذات سر مشترك
حتى لحركة Serve. ثم استخدم `gateway.auth.mode: "token"` أو
من الهوية عبر حل عنوان `x-forwarded-for` باستخدام
`tailscale whois` ومطابقته مع الترويسة، ولا يقبل هذه الترويسات إلا عندما
يضرب الطلب loopback مع ترويسات `x-forwarded-*` الخاصة بـ Tailscale. اضبط
`gateway.auth.allowTailscale: false` إذا كنت تريد فرض بيانات اعتماد صريحة قائمة على السر المشترك
حتى مع حركة Serve. ثم استخدم `gateway.auth.mode: "token"` أو
`"password"`.
وفي هذا المسار غير المتزامن لهوية Serve، تتم موازاة محاولات المصادقة الفاشلة للعنوان IP نفسه
ولنطاق المصادقة نفسه قبل كتابة بيانات تحديد المعدل. لذلك يمكن أن تُظهر
إعادات المحاولة السيئة المتزامنة من المتصفح نفسه الرسالة `retry later` في الطلب الثاني
بدلًا من حالتي عدم تطابق عاديتين تتسابقان بالتوازي.
تفترض مصادقة Serve من دون token أن مضيف gateway موثوق. وإذا كان يمكن لتعليمات برمجية
محلية غير موثوقة أن تعمل على ذلك المضيف، فاشترط مصادقة token/password.
وبالنسبة إلى مسار هوية Serve غير المتزامن هذا، تُسلسَل
محاولات المصادقة الفاشلة للنطاق نفسه من IP العميل نفسه قبل كتابات
تحديد المعدل. لذلك فإن محاولات الإعادة السيئة المتزامنة من المتصفح نفسه
قد تُظهر `retry later` في الطلب الثاني بدلًا من حدوث حالتي عدم تطابق عاديتين بشكل متوازٍ.
تفترض المصادقة من دون رمز في Serve أن مضيف Gateway موثوق. وإذا أمكن تشغيل
كود محلي غير موثوق على ذلك المضيف، فاطلب مصادقة بالرمز/كلمة المرور.
### الربط بـ tailnet + token
### الربط بـ tailnet + رمز
```bash
openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)"
@ -243,29 +236,29 @@ openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)"
ثم افتح:
- `http://<tailscale-ip>:18789/` (أو `gateway.controlUi.basePath` الذي قمت بتكوينه)
- `http://<tailscale-ip>:18789/` (أو `gateway.controlUi.basePath` المضبوط لديك)
ألصق السر المشترك المطابق في إعدادات واجهة المستخدم (ويُرسل كـ
الصق السر المشترك المطابق في إعدادات واجهة المستخدم (ويُرسل كـ
`connect.params.auth.token` أو `connect.params.auth.password`).
## ‏HTTP غير الآمن
## HTTP غير الآمن
إذا فتحت dashboard عبر HTTP عادي (`http://<lan-ip>` أو `http://<tailscale-ip>`)،
إذا فتحت لوحة المعلومات عبر HTTP عادي (`http://<lan-ip>` أو `http://<tailscale-ip>`)،
فإن المتصفح يعمل ضمن **سياق غير آمن** ويمنع WebCrypto. افتراضيًا،
يقوم OpenClaw **بحظر** اتصالات Control UI من دون هوية جهاز.
الاستثناءات الموثقة:
- توافق HTTP غير الآمن الخاص بـ localhost فقط مع `gateway.controlUi.allowInsecureAuth=true`
- نجاح مصادقة operator في Control UI عبر `gateway.auth.mode: "trusted-proxy"`
- توافق HTTP غير الآمن الخاص بـ localhost فقط باستخدام `gateway.controlUi.allowInsecureAuth=true`
- نجاح مصادقة المشغّل في Control UI عبر `gateway.auth.mode: "trusted-proxy"`
- خيار الطوارئ `gateway.controlUi.dangerouslyDisableDeviceAuth=true`
**الإصلاح الموصى به:** استخدم HTTPS ‏(Tailscale Serve) أو افتح واجهة المستخدم محليًا:
**الإصلاح الموصى به:** استخدم HTTPS (عبر Tailscale Serve) أو افتح الواجهة محليًا:
- `https://<magicdns>/` ‏(Serve)
- `http://127.0.0.1:18789/` ‏(على مضيف gateway)
- `https://<magicdns>/` (Serve)
- `http://127.0.0.1:18789/` (على مضيف Gateway)
**سلوك مفتاح insecure-auth:**
**سلوك مفتاح تبديل المصادقة غير الآمنة:**
```json5
{
@ -277,12 +270,12 @@ openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)"
}
```
إن `allowInsecureAuth` هو مفتاح توافق محلي فقط:
`allowInsecureAuth` هو مفتاح توافق محلي فقط:
- يسمح لجلسات Control UI الخاصة بـ localhost بالاستمرار من دون هوية جهاز في
- يسمح لجلسات Control UI على localhost بالمتابعة من دون هوية جهاز في
سياقات HTTP غير الآمنة.
- لا يتجاوز فحوصات الاقتران.
- لا يخفف متطلبات هوية الجهاز عن الاتصالات البعيدة (غير localhost).
- لا يتجاوز فحوصات الإقران.
- لا يخفف متطلبات هوية الجهاز البعيدة (غير localhost).
**للطوارئ فقط:**
@ -296,40 +289,40 @@ openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)"
}
```
يعطل `dangerouslyDisableDeviceAuth` فحوصات هوية الجهاز في Control UI ويُعد
تخفيضًا أمنيًا خطيرًا. أعد التراجع عنه سريعًا بعد الاستخدام الطارئ.
يقوم `dangerouslyDisableDeviceAuth` بتعطيل فحوصات هوية جهاز Control UI ويُعد
خفضًا أمنيًا شديدًا. أعد التراجع عنه بسرعة بعد الاستخدام الطارئ.
ملاحظة trusted-proxy:
- يمكن لمصادقة trusted-proxy الناجحة أن تسمح بجلسات Control UI من نوع **operator** من دون
- يمكن لمصادقة trusted-proxy الناجحة أن تسمح بجلسات Control UI الخاصة بـ **operator** من دون
هوية جهاز
- لا يمتد هذا إلى جلسات Control UI ذات دور Node
- لا تزال الوكلاء العكسية عبر loopback على المضيف نفسه لا تستوفي مصادقة trusted-proxy؛ راجع
- هذا **لا** يمتد إلى جلسات Control UI ذات دور node
- لا تزال الوكلاء العكسية ذات loopback على المضيف نفسه لا تستوفي مصادقة trusted-proxy؛ راجع
[Trusted Proxy Auth](/ar/gateway/trusted-proxy-auth)
راجع [Tailscale](/ar/gateway/tailscale) للحصول على إرشادات إعداد HTTPS.
راجع [Tailscale](/ar/gateway/tailscale) لإرشادات إعداد HTTPS.
## ‏Content Security Policy
## سياسة أمان المحتوى
تشحن Control UI بسياسة `img-src` صارمة: يُسمح فقط بالأصول **من الأصل نفسه** وعناوين `data:` URL. أما عناوين الصور البعيدة `http(s)` والعناوين النسبية للبروتوكول فتُرفض من المتصفح ولا تُصدر طلبات جلب عبر الشبكة.
تأتي Control UI بسياسة `img-src` محكمة: يُسمح فقط بالأصول ذات **الأصل نفسه** وعناوين URL من نوع `data:`. تُرفض عناوين الصور البعيدة `http(s)` والعناوين النسبية للبروتوكول من قبل المتصفح ولا تصدر أي طلبات شبكة.
ما الذي يعنيه ذلك عمليًا:
ما يعنيه هذا عمليًا:
- لا تزال الصور الرمزية والصور المقدَّمة تحت مسارات نسبية (مثل `/avatars/<id>`) تُعرض.
- لا تزال عناوين `data:image/...` URL المضمنة تُعرض (وهي مفيدة للحمولات ضمن البروتوكول).
- تُجرّد عناوين الصور الرمزية البعيدة التي تصدرها بيانات القناة الوصفية في مساعدات الصورة الرمزية الخاصة بـ Control UI وتُستبدل بالشعار/الوسام المضمّن، بحيث لا تتمكن قناة مخترقة أو خبيثة من فرض جلب صور بعيدة تعسفية من متصفح المشغّل.
- لا تزال الصور الرمزية والصور المقدمة عبر مسارات نسبية (مثل `/avatars/<id>`) تُعرض.
- لا تزال عناوين `data:image/...` المضمنة تُعرض (وهو مفيد للحمولات داخل البروتوكول).
- تُزال عناوين الصور الرمزية البعيدة الصادرة من بيانات القناة الوصفية في مساعدات الصور الرمزية في Control UI وتُستبدل بالشعار/الشارة المدمجين، بحيث لا تستطيع قناة مخترقة أو خبيثة فرض جلب صور بعيدة عشوائية من متصفح المشغّل.
لا تحتاج إلى تغيير أي شيء للحصول على هذا السلوك — فهو مفعّل دائمًا وغير قابل للتكوين.
لا تحتاج إلى تغيير أي شيء للحصول على هذا السلوك — فهو دائم التفعيل وغير قابل للتكوين.
## مصادقة مسار الصورة الرمزية
عندما تكون مصادقة gateway مضبوطة، تتطلب نقطة نهاية الصورة الرمزية في Control UI رمز gateway نفسه مثل بقية API:
عندما تكون مصادقة Gateway مضبوطة، تتطلب نقطة نهاية الصورة الرمزية في Control UI الرمز نفسه الخاص بـ Gateway مثل بقية API:
- يعيد `GET /avatar/<agentId>` صورة الصورة الرمزية فقط للمستدعين المصادق عليهم. ويعيد `GET /avatar/<agentId>?meta=1` بيانات الصورة الرمزية الوصفية وفق القاعدة نفسها.
- تُرفض الطلبات غير المصادق عليها لكلا المسارين (بما يطابق مسار وسائط المساعد الشقيق). وهذا يمنع مسار الصورة الرمزية من تسريب هوية الوكيل على المضيفين المحميين بخلاف ذلك.
- تقوم Control UI نفسها بتمرير رمز gateway كرأس bearer عند جلب الصور الرمزية، وتستخدم blob URLs مصادقًا عليها حتى تظل الصورة معروضة في dashboards.
- يعيد `GET /avatar/<agentId>` صورة الصورة الرمزية فقط للمتصلين المصادَق عليهم. ويعيد `GET /avatar/<agentId>?meta=1` بيانات الصورة الرمزية الوصفية وفق القاعدة نفسها.
- تُرفض الطلبات غير المصادَق عليها إلى أي من المسارين (بما يطابق المسار الشقيق الخاص بوسائط المساعد). وهذا يمنع مسار الصورة الرمزية من تسريب هوية الوكيل على المضيفات المحمية بخلاف ذلك.
- تقوم Control UI نفسها بتمرير رمز Gateway كترويسة bearer عند جلب الصور الرمزية، وتستخدم عناوين blob URL مصادَق عليها حتى تستمر الصورة في الظهور في لوحات المعلومات.
إذا عطلت مصادقة gateway (وهو أمر غير موصى به على المضيفين المشتركين)، يصبح مسار الصورة الرمزية أيضًا غير مصادق عليه، بما يتماشى مع بقية gateway.
إذا عطلت مصادقة Gateway (وهو غير موصى به على المضيفات المشتركة)، يصبح مسار الصورة الرمزية أيضًا غير مصادَق عليه، بما يتماشى مع بقية Gateway.
## بناء واجهة المستخدم
@ -339,7 +332,7 @@ openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)"
pnpm ui:build
```
بادئة مطلقة اختيارية (عندما تريد عناوين URL ثابتة للأصول):
قاعدة مطلقة اختيارية (عندما تريد عناوين أصول ثابتة):
```bash
OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build
@ -351,15 +344,15 @@ OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build
pnpm ui:dev
```
ثم وجّه واجهة المستخدم إلى عنوان WS الخاص بـ Gateway لديك (مثل `ws://127.0.0.1:18789`).
ثم وجّه الواجهة إلى عنوان Gateway WS الخاص بك (مثل `ws://127.0.0.1:18789`).
## التصحيح/الاختبار: خادم تطوير + Gateway بعيد
إن Control UI عبارة عن ملفات ثابتة؛ وهدف WebSocket قابل للتكوين ويمكن أن
يختلف عن أصل HTTP. وهذا مفيد عندما تريد تشغيل خادم Vite للتطوير محليًا
بينما يعمل Gateway في مكان آخر.
Control UI عبارة عن ملفات ثابتة؛ وهدف WebSocket قابل للتكوين ويمكن أن يكون
مختلفًا عن أصل HTTP. وهذا مفيد عندما تريد خادم تطوير Vite
محليًا لكن يعمل Gateway في مكان آخر.
1. ابدأ خادم تطوير UI: ‏`pnpm ui:dev`
1. ابدأ خادم تطوير الواجهة: `pnpm ui:dev`
2. افتح عنوان URL مثل:
```text
@ -374,20 +367,20 @@ http://localhost:5173/?gatewayUrl=wss://<gateway-host>:18789#token=<gateway-toke
ملاحظات:
- يتم تخزين `gatewayUrl` في localStorage بعد التحميل ثم يُزال من عنوان URL.
- ينبغي تمرير `token` عبر مقطع URL ‏(`#token=...`) كلما أمكن. فالمقاطع لا تُرسل إلى الخادم، مما يتجنب تسرب سجلات الطلبات وReferer. ولا تزال معلمات الاستعلام القديمة `?token=` تُستورد مرة واحدة للتوافق، لكن كرجوع احتياطي فقط، ويتم تجريدها فورًا بعد bootstrap.
- يبقى `password` في الذاكرة فقط.
- عندما يكون `gatewayUrl` مضبوطًا، لا تعود واجهة المستخدم إلى بيانات الاعتماد الموجودة في التكوين أو البيئة.
مرّر `token` (أو `password`) صراحةً. ويُعد غياب بيانات الاعتماد الصريحة خطأ.
- استخدم `wss://` عندما يكون Gateway خلف TLS ‏(Tailscale Serve، أو HTTPS proxy، إلخ).
- لا يُقبل `gatewayUrl` إلا في نافذة من المستوى الأعلى (وليس عند التضمين) لمنع clickjacking.
- يجب على عمليات نشر Control UI غير المعتمدة على loopback أن تضبط `gateway.controlUi.allowedOrigins`
صراحةً (أصول كاملة). ويشمل هذا إعدادات التطوير البعيدة.
- لا تستخدم `gateway.controlUi.allowedOrigins: ["*"]` إلا في
الاختبارات المحلية المضبوطة بإحكام. فهذا يعني السماح لأي أصل متصفح، وليس "مطابقة أي مضيف
- يُحفَظ `gatewayUrl` في `localStorage` بعد التحميل ويُزال من عنوان URL.
- يجب تمرير `token` عبر جزء عنوان URL (`#token=...`) كلما أمكن. لا تُرسل الأجزاء إلى الخادم، ما يمنع تسربها في سجلات الطلبات وReferer. ما زالت معاملات الاستعلام القديمة `?token=` تُستورد مرة واحدة للتوافق، لكن فقط كحل احتياطي، وتُزال فورًا بعد التهيئة.
- تُحفَظ `password` في الذاكرة فقط.
- عندما يكون `gatewayUrl` مضبوطًا، لا تعود الواجهة إلى بيانات الاعتماد من التكوين أو البيئة.
قدّم `token` (أو `password`) صراحةً. ويُعد غياب بيانات الاعتماد الصريحة خطأً.
- استخدم `wss://` عندما يكون Gateway خلف TLS (مثل Tailscale Serve أو وكيل HTTPS، إلخ).
- لا يُقبل `gatewayUrl` إلا في نافذة من المستوى الأعلى (وليس ضمن تضمين) لمنع clickjacking.
- يجب على عمليات نشر Control UI غير المعتمدة على loopback ضبط `gateway.controlUi.allowedOrigins`
صراحةً (كأصول كاملة). وهذا يشمل إعدادات التطوير البعيدة.
- لا تستخدم `gateway.controlUi.allowedOrigins: ["*"]` إلا لاختبارات
محلية محكومة بإحكام. فهذا يعني السماح لأي أصل متصفح، وليس "مطابقة أي مضيف
أستخدمه".
- يفعّل `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true`
وضع الرجوع الاحتياطي لأصل Host-header، لكنه وضع أمني خطير.
- يؤدي `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` إلى تمكين
وضع الرجوع الاحتياطي لأصل ترويسة Host، لكنه وضع أمني خطير.
مثال:
@ -405,7 +398,7 @@ http://localhost:5173/?gatewayUrl=wss://<gateway-host>:18789#token=<gateway-toke
## ذو صلة
- [Dashboard](/ar/web/dashboard) — لوحة Gateway
- [WebChat](/ar/web/webchat) — واجهة دردشة معتمدة على المتصفح
- [Dashboard](/ar/web/dashboard) — لوحة معلومات Gateway
- [WebChat](/ar/web/webchat) — واجهة دردشة مستندة إلى المتصفح
- [TUI](/ar/web/tui) — واجهة مستخدم طرفية
- [Health Checks](/ar/gateway/health) — مراقبة صحة Gateway
- [فحوصات الصحة](/ar/gateway/health) — مراقبة صحة Gateway