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-05 13:01:11 +00:00
parent 2ca2db1564
commit 051ca43b21
397 changed files with 89706 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

81
docs/ar/.i18n/README.md Normal file
View File

@ -0,0 +1,81 @@
---
x-i18n:
generated_at: "2026-04-05T12:34:06Z"
model: gpt-5.4
provider: openai
source_hash: adff26fa8858af2759b231ea48bfc01f89c110cd9b3774a8f783e282c16f77fb
source_path: .i18n/README.md
workflow: 15
---
# أصول التدويل لوثائق OpenClaw
يخزن هذا المجلد إعدادات الترجمة لمستودع وثائق المصدر.
توجد الآن أشجار اللغات المُولدة وذاكرة الترجمة الحية في مستودع النشر:
- المستودع: `openclaw/docs`
- النسخة المحلية: `~/Projects/openclaw-docs`
## المصدر المعتمد
- تتم كتابة الوثائق الإنجليزية في `openclaw/openclaw`.
- توجد شجرة وثائق المصدر ضمن `docs/`.
- لم يعد مستودع المصدر يحتفظ بأشجار اللغات المُولدة الملتزم بها مثل `docs/zh-CN/**` و`docs/ja-JP/**` و`docs/es/**` و`docs/pt-BR/**` و`docs/ko/**` و`docs/de/**` و`docs/fr/**` أو `docs/ar/**`.
## التدفق الكامل
1. حرر الوثائق الإنجليزية في `openclaw/openclaw`.
2. ادفع إلى `main`.
3. يقوم `openclaw/openclaw/.github/workflows/docs-sync-publish.yml` بعكس شجرة الوثائق إلى `openclaw/docs`.
4. يعيد نص المزامنة كتابة ملف النشر `docs/docs.json` بحيث توجد كتل منتقي اللغات المُولدة هناك رغم أنها لم تعد مُلتزمًا بها في مستودع المصدر.
5. يقوم `openclaw/docs/.github/workflows/translate-zh-cn.yml` بتحديث `docs/zh-CN/**` مرة يوميًا، وعند الطلب، وبعد عمليات إرسال الإصدارات من مستودع المصدر.
6. يقوم `openclaw/docs/.github/workflows/translate-ja-jp.yml` بالأمر نفسه لـ `docs/ja-JP/**`.
7. تقوم `openclaw/docs/.github/workflows/translate-es.yml` و`translate-pt-br.yml` و`translate-ko.yml` و`translate-de.yml` و`translate-fr.yml` و`translate-ar.yml` بالأمر نفسه لـ `docs/es/**` و`docs/pt-BR/**` و`docs/ko/**` و`docs/de/**` و`docs/fr/**` و`docs/ar/**`.
## سبب هذا الفصل
- إبقاء مخرجات اللغات المُولدة خارج مستودع المنتج الرئيسي.
- إبقاء Mintlify على شجرة وثائق منشورة واحدة.
- الحفاظ على مبدل اللغة المدمج عبر جعل مستودع النشر يملك أشجار اللغات المُولدة.
## الملفات في هذا المجلد
- `glossary.<lang>.json` — تعيينات المصطلحات المفضلة المستخدمة كإرشادات للمطالبة.
- `ar-navigation.json` و`de-navigation.json` و`es-navigation.json` و`fr-navigation.json` و`ja-navigation.json` و`ko-navigation.json` و`pt-BR-navigation.json` و`zh-Hans-navigation.json` — كتل منتقي اللغات في Mintlify التي يُعاد إدراجها في مستودع النشر أثناء المزامنة.
- `<lang>.tm.jsonl` — ذاكرة ترجمة مفهرسة بحسب سير العمل + النموذج + تجزئة النص.
في هذا المستودع، لم تعد ملفات TM الخاصة باللغات المُولدة مثل `docs/.i18n/zh-CN.tm.jsonl` و`docs/.i18n/ja-JP.tm.jsonl` و`docs/.i18n/es.tm.jsonl` و`docs/.i18n/pt-BR.tm.jsonl` و`docs/.i18n/ko.tm.jsonl` و`docs/.i18n/de.tm.jsonl` و`docs/.i18n/fr.tm.jsonl` و`docs/.i18n/ar.tm.jsonl` مُلتزمًا بها عمدًا.
## تنسيق المسرد
`glossary.<lang>.json` عبارة عن مصفوفة من الإدخالات:
```json
{
"source": "troubleshooting",
"target": "故障排除"
}
```
الحقول:
- `source`: العبارة الإنجليزية (أو عبارة المصدر) المفضلة.
- `target`: مخرجات الترجمة المفضلة.
## آلية الترجمة
- ما يزال `scripts/docs-i18n` مسؤولًا عن توليد الترجمة.
- يكتب وضع الوثائق `x-i18n.source_hash` داخل كل صفحة مترجمة.
- يحسب كل سير عمل نشر مسبقًا قائمة الملفات المعلقة عبر مقارنة تجزئة المصدر الإنجليزي الحالية مع `x-i18n.source_hash` المخزن للغة.
- إذا كان عدد الملفات المعلقة `0`، فسيتم تخطي خطوة الترجمة المكلفة بالكامل.
- إذا كانت هناك ملفات معلقة، يترجم سير العمل تلك الملفات فقط.
- يعيد سير عمل النشر المحاولة عند حدوث إخفاقات عابرة في تنسيق النموذج، لكن الملفات غير المتغيرة تبقى متخطاة لأن فحص التجزئة نفسه يعمل في كل إعادة محاولة.
- يرسل مستودع المصدر أيضًا تحديثات zh-CN وja-JP وes وpt-BR وko وde وfr وar بعد إصدارات GitHub المنشورة حتى تتمكن وثائق الإصدار من اللحاق دون انتظار المهمة اليومية المجدولة.
## ملاحظات تشغيلية
- تتم كتابة بيانات تعريف المزامنة إلى `.openclaw-sync/source.json` في مستودع النشر.
- السر في مستودع المصدر: `OPENCLAW_DOCS_SYNC_TOKEN`
- السر في مستودع النشر: `OPENCLAW_DOCS_I18N_OPENAI_API_KEY`
- إذا بدا أن مخرجات اللغة قديمة، فتحقق أولًا من سير عمل `Translate <locale>` المطابق في `openclaw/docs`.

87
docs/ar/auth-credential-semantics.md Normal file
View File

@ -0,0 +1,87 @@
---
read_when:
- العمل على حل ملفات تعريف المصادقة أو توجيه بيانات الاعتماد
- تصحيح فشل مصادقة النموذج أو ترتيب ملفات التعريف
summary: دلالات الأهلية والحل القانونية لبيانات الاعتماد لملفات تعريف المصادقة
title: دلالات بيانات اعتماد المصادقة
x-i18n:
generated_at: "2026-04-05T12:34:04Z"
model: gpt-5.4
provider: openai
source_hash: a4cd3e16cd25eb22c5e707311d06a19df1a59747ee3261c2d32c534a245fd7fb
source_path: auth-credential-semantics.md
workflow: 15
---
# دلالات بيانات اعتماد المصادقة
يعرّف هذا المستند دلالات الأهلية والحل القانونية لبيانات الاعتماد المستخدمة عبر:
- `resolveAuthProfileOrder`
- `resolveApiKeyForProfile`
- `models status --probe`
- `doctor-auth`
الهدف هو إبقاء سلوك وقت الاختيار ووقت التشغيل متوافقًا.
## رموز أسباب الفحص المستقرة
- `ok`
- `excluded_by_auth_order`
- `missing_credential`
- `invalid_expires`
- `expired`
- `unresolved_ref`
- `no_model`
## بيانات اعتماد الرمز المميز
تدعم بيانات اعتماد الرمز المميز (`type: "token"`) قيمة `token` المضمنة و/أو `tokenRef`.
### قواعد الأهلية
1. يكون ملف تعريف الرمز المميز غير مؤهل عندما يكون كل من `token` و`tokenRef` غير موجودين.
2. `expires` اختياري.
3. إذا كانت `expires` موجودة، فيجب أن تكون رقمًا منتهيًا أكبر من `0`.
4. إذا كانت `expires` غير صالحة (`NaN` أو `0` أو سالبة أو غير منتهية أو من نوع خاطئ)، يكون ملف التعريف غير مؤهل مع `invalid_expires`.
5. إذا كانت `expires` في الماضي، يكون ملف التعريف غير مؤهل مع `expired`.
6. لا يتجاوز `tokenRef` التحقق من `expires`.
### قواعد الحل
1. تتطابق دلالات أداة الحل مع دلالات الأهلية بالنسبة إلى `expires`.
2. بالنسبة إلى ملفات التعريف المؤهلة، يمكن حل مادة الرمز المميز من القيمة المضمنة أو `tokenRef`.
3. تؤدي المراجع غير القابلة للحل إلى `unresolved_ref` في مخرجات `models status --probe`.
## التصفية الصريحة لترتيب المصادقة
- عندما يتم تعيين `auth.order.<provider>` أو تجاوز ترتيب مخزن المصادقة
لموفّر ما، فإن `models status --probe` يفحص فقط معرّفات ملفات التعريف التي تبقى في
ترتيب المصادقة المحلول لذلك الموفّر.
- لا تتم محاولة ملف تعريف مخزن لذلك الموفّر تم حذفه من الترتيب الصريح
لاحقًا بشكل صامت. وتبلّغ مخرجات الفحص عنه باستخدام
`reasonCode: excluded_by_auth_order` والتفصيل
`Excluded by auth.order for this provider.`
## حل أهداف الفحص
- يمكن أن تأتي أهداف الفحص من ملفات تعريف المصادقة أو بيانات اعتماد البيئة أو
`models.json`.
- إذا كان لدى موفّر بيانات اعتماد ولكن OpenClaw لا يمكنه حل مرشح
نموذج قابل للفحص له، فإن `models status --probe` يبلّغ عن `status: no_model` مع
`reasonCode: no_model`.
## حاجز سياسة SecretRef لـ OAuth
- إدخال SecretRef مخصص لبيانات الاعتماد الثابتة فقط.
- إذا كانت بيانات اعتماد ملف التعريف من النوع `type: "oauth"`، فلا يتم دعم كائنات SecretRef لمادة بيانات اعتماد ملف التعريف تلك.
- إذا كان `auth.profiles.<id>.mode` يساوي `"oauth"`، فيتم رفض إدخال `keyRef`/`tokenRef` المدعوم بـ SecretRef لذلك الملف التعريفي.
- الانتهاكات هي حالات فشل صارمة في مسارات حل المصادقة عند بدء التشغيل/إعادة التحميل.
## الرسائل المتوافقة مع الإصدارات القديمة
للتوافق مع البرامج النصية، تحتفظ أخطاء الفحص بهذا السطر الأول دون تغيير:
`Auth profile credentials are missing or expired.`
يمكن إضافة تفاصيل سهلة الفهم ورموز أسباب مستقرة في الأسطر اللاحقة.

15
docs/ar/automation/auth-monitoring.md Normal file
View File

@ -0,0 +1,15 @@
---
summary: إعادة التوجيه إلى /gateway/authentication
title: مراقبة المصادقة
x-i18n:
generated_at: "2026-04-05T12:33:53Z"
model: gpt-5.4
provider: openai
source_hash: 42aa1b4aa76201b20e07d8ad77231607855e7e7421fa032830055144ccd8819a
source_path: automation/auth-monitoring.md
workflow: 15
---
# مراقبة المصادقة
تم نقل هذه الصفحة إلى [المصادقة](/gateway/authentication). راجع [المصادقة](/gateway/authentication) للاطلاع على وثائق مراقبة المصادقة.

15
docs/ar/automation/clawflow.md Normal file
View File

@ -0,0 +1,15 @@
---
summary: إعادة التوجيه إلى Task Flow
title: ClawFlow
x-i18n:
generated_at: "2026-04-05T12:33:54Z"
model: gpt-5.4
provider: openai
source_hash: e644237e0812f25b46a06ff125c8858dbc69a499aa43cfd73cf7cb37572e78e6
source_path: automation/clawflow.md
workflow: 15
---
# ClawFlow
تمت إعادة تسمية ClawFlow إلى [Task Flow](/automation/taskflow). راجع [Task Flow](/automation/taskflow) للاطلاع على الوثائق الحالية.

413
docs/ar/automation/cron-jobs.md Normal file
View File

@ -0,0 +1,413 @@
---
read_when:
- عند جدولة المهام الخلفية أو عمليات الإيقاظ
- عند توصيل المشغلات الخارجية (webhooks وGmail) إلى OpenClaw
- عند اتخاذ قرار بين heartbeat وcron للمهام المجدولة
summary: المهام المجدولة وwebhooks ومشغلات Gmail PubSub لجدولة Gateway
title: المهام المجدولة
x-i18n:
generated_at: "2026-04-05T12:34:48Z"
model: gpt-5.4
provider: openai
source_hash: 43b906914461aba9af327e7e8c22aa856f65802ec2da37ed0c4f872d229cfde6
source_path: automation/cron-jobs.md
workflow: 15
---
# المهام المجدولة (Cron)
Cron هو المجدول المدمج في Gateway. فهو يحتفظ بالمهام، ويوقظ الوكيل في الوقت المناسب، ويمكنه إعادة تسليم المخرجات إلى قناة دردشة أو نقطة نهاية webhook.
## بدء سريع
```bash
# Add a one-shot reminder
openclaw cron add \
--name "Reminder" \
--at "2026-02-01T16:00:00Z" \
--session main \
--system-event "Reminder: check the cron docs draft" \
--wake now \
--delete-after-run
# Check your jobs
openclaw cron list
# See run history
openclaw cron runs --id <job-id>
```
## كيف يعمل cron
- يعمل Cron **داخل** عملية Gateway (وليس داخل النموذج).
- تُحفَظ المهام في `~/.openclaw/cron/jobs.json` بحيث لا تؤدي عمليات إعادة التشغيل إلى فقدان الجداول.
- تنشئ جميع عمليات تنفيذ cron سجلات [المهام الخلفية](/automation/tasks).
- تُحذف المهام ذات التشغيل الواحد (`--at`) تلقائيًا بعد النجاح افتراضيًا.
- تحاول عمليات cron المعزولة، بأفضل جهد ممكن، إغلاق علامات تبويب/عمليات المتصفح المتتبعة الخاصة بجلسة `cron:<jobId>` عند اكتمال التشغيل، حتى لا تترك أتمتة المتصفح المفصولة عمليات يتيمة وراءها.
- تحمي عمليات cron المعزولة أيضًا من ردود الإقرار القديمة. إذا كانت
النتيجة الأولى مجرد تحديث حالة مؤقت (`on it` و`pulling everything
together` وتلميحات مشابهة) ولم يعد أي تشغيل تابع منحدر لا يزال
مسؤولًا عن الإجابة النهائية، فإن OpenClaw يعيد المطالبة مرة واحدة للحصول على
النتيجة الفعلية قبل التسليم.
تسوية المهام لـ cron مملوكة لوقت التشغيل: تبقى مهمة cron النشطة قيد التشغيل ما دام
وقت تشغيل cron لا يزال يتتبع تلك المهمة على أنها قيد التشغيل، حتى إذا كان صف جلسة فرعي قديم لا يزال موجودًا.
وبمجرد أن يتوقف وقت التشغيل عن امتلاك المهمة وتنتهي مهلة السماح البالغة 5 دقائق، يمكن للصيانة
وضع علامة `lost` على المهمة.
## أنواع الجداول
| النوع | علم CLI | الوصف |
| ------- | --------- | ------------------------------------------------------- |
| `at` | `--at` | طابع زمني لتشغيل واحد (ISO 8601 أو قيمة نسبية مثل `20m`) |
| `every` | `--every` | فاصل زمني ثابت |
| `cron` | `--cron` | تعبير cron من 5 أو 6 حقول مع `--tz` اختياري |
تُعامل الطوابع الزمنية التي لا تحتوي على منطقة زمنية على أنها UTC. أضف `--tz America/New_York` للجدولة حسب التوقيت المحلي الفعلي.
تُوزَّع تعبيرات التكرار أعلى كل ساعة تلقائيًا بفارق يصل إلى 5 دقائق لتقليل ارتفاعات الحمل. استخدم `--exact` لفرض توقيت دقيق أو `--stagger 30s` لنافذة صريحة.
## أنماط التنفيذ
| النمط | قيمة `--session` | يعمل في | الأنسب لـ |
| --------------- | ------------------- | ------------------------ | ------------------------------- |
| الجلسة الرئيسية | `main` | دورة heartbeat التالية | التذكيرات، وأحداث النظام |
| معزول | `isolated` | `cron:<jobId>` مخصصة | التقارير، والمهام الخلفية |
| الجلسة الحالية | `current` | يُربط وقت الإنشاء | الأعمال الدورية المعتمدة على السياق |
| جلسة مخصصة | `session:custom-id` | جلسة مسماة دائمة | سير العمل الذي يعتمد على السجل |
تضيف مهام **الجلسة الرئيسية** حدث نظام إلى قائمة الانتظار، ويمكنها اختياريًا إيقاظ heartbeat (`--wake now` أو `--wake next-heartbeat`). تعمل المهام **المعزولة** بدورة وكيل مخصصة مع جلسة جديدة. تحتفظ **الجلسات المخصصة** (`session:xxx`) بالسياق عبر مرات التشغيل، مما يتيح سير عمل مثل الاجتماعات اليومية المختصرة التي تعتمد على الملخصات السابقة.
بالنسبة للمهام المعزولة، يتضمن التفكيك في وقت التشغيل الآن تنظيف المتصفح، بأفضل جهد، لتلك الجلسة الخاصة بـ cron. ويتم تجاهل إخفاقات التنظيف بحيث تبقى نتيجة cron الفعلية هي المعتمدة.
عندما تقوم عمليات cron المعزولة بتنسيق وكلاء فرعيين، يفضّل التسليم أيضًا
المخرجات النهائية التابعة بدلًا من النص المؤقت القديم للأصل. وإذا كانت العمليات التابعة لا تزال
قيد التشغيل، فإن OpenClaw يحجب هذا التحديث الجزئي من الأصل بدلًا من إعلانه.
### خيارات الحمولة للمهام المعزولة
- `--message`: نص المطالبة (مطلوب للمهام المعزولة)
- `--model` / `--thinking`: تجاوزات النموذج ومستوى التفكير
- `--light-context`: تخطي حقن ملف تهيئة مساحة العمل
- `--tools exec,read`: تقييد الأدوات التي يمكن للمهمة استخدامها
يستخدم `--model` النموذج المسموح المحدد لتلك المهمة. إذا كان النموذج المطلوب
غير مسموح به، يسجل cron تحذيرًا ويعود إلى اختيار نموذج الوكيل/الافتراضي
لتلك المهمة بدلًا من ذلك. وتظل سلاسل التراجع المهيأة مطبقة، لكن تجاوز
النموذج العادي من دون قائمة تراجع صريحة لكل مهمة لم يعد يضيف النموذج
الأساسي للوكيل كهدف إعادة محاولة إضافي مخفي.
أولوية اختيار النموذج للمهام المعزولة هي:
1. تجاوز نموذج hook الخاص بـ Gmail (عندما يكون التشغيل قادمًا من Gmail ويكون هذا التجاوز مسموحًا)
2. `model` في حمولة كل مهمة
3. تجاوز النموذج المخزن لجلسة cron
4. اختيار نموذج الوكيل/الافتراضي
يتبع الوضع السريع اختيار التشغيل المباشر الذي تم حله أيضًا. إذا كان إعداد النموذج المحدد
يحتوي على `params.fastMode`، فإن cron المعزول يستخدم ذلك افتراضيًا. ويظل تجاوز
`fastMode` المخزن للجلسة متقدمًا على الإعداد في كلا الاتجاهين.
إذا واجه تشغيل معزول تسليمًا مباشرًا لتبديل النموذج، يعيد cron المحاولة باستخدام
المزوّد/النموذج المُبدَّل ويحفظ هذا الاختيار المباشر قبل إعادة المحاولة. وعندما
يحمل التبديل أيضًا ملف تعريف مصادقة جديدًا، فإن cron يحفظ تجاوز ملف تعريف المصادقة هذا أيضًا.
إعادات المحاولة محدودة: بعد المحاولة الأولية بالإضافة إلى محاولتي تبديل،
يُجهِض cron بدلًا من الدخول في حلقة لا نهائية.
## التسليم والمخرجات
| الوضع | ما الذي يحدث |
| ---------- | -------------------------------------------------------- |
| `announce` | تسليم الملخص إلى القناة المستهدفة (الافتراضي للمهام المعزولة) |
| `webhook` | إرسال حمولة حدث الاكتمال إلى URL عبر POST |
| `none` | داخلي فقط، بلا تسليم |
استخدم `--announce --channel telegram --to "-1001234567890"` للتسليم إلى قناة. بالنسبة لموضوعات منتدى Telegram، استخدم `-1001234567890:topic:123`. يجب أن تستخدم أهداف Slack/Discord/Mattermost بادئات صريحة (`channel:<id>` و`user:<id>`).
بالنسبة للمهام المعزولة المملوكة لـ cron، يمتلك المشغّل مسار التسليم النهائي. تتم
مطالبة الوكيل بإرجاع ملخص نصي عادي، ثم يُرسل هذا الملخص عبر
`announce` أو `webhook` أو يُحتفظ به داخليًا عند `none`. لا يعيد `--no-deliver`
التسليم إلى الوكيل؛ بل يُبقي التشغيل داخليًا.
إذا كانت المهمة الأصلية تنص صراحةً على إرسال رسالة إلى مستلم خارجي ما، فيجب على
الوكيل أن يذكر في مخرجاته إلى من/أين ينبغي أن تذهب تلك الرسالة بدلًا من
محاولة إرسالها مباشرةً.
تتبع إشعارات الفشل مسار وجهة منفصلًا:
- يعيّن `cron.failureDestination` القيمة الافتراضية العامة لإشعارات الفشل.
- يتجاوز `job.delivery.failureDestination` ذلك لكل مهمة.
- إذا لم يُضبط أي منهما وكانت المهمة تسلّم بالفعل عبر `announce`، فإن إشعارات الفشل تعود الآن إلى هدف announce الأساسي هذا.
- لا يكون `delivery.failureDestination` مدعومًا إلا في المهام ذات `sessionTarget="isolated"` ما لم يكن وضع التسليم الأساسي هو `webhook`.
## أمثلة CLI
تذكير بتشغيل واحد (الجلسة الرئيسية):
```bash
openclaw cron add \
--name "Calendar check" \
--at "20m" \
--session main \
--system-event "Next heartbeat: check calendar." \
--wake now
```
مهمة معزولة متكررة مع تسليم:
```bash
openclaw cron add \
--name "Morning brief" \
--cron "0 7 * * *" \
--tz "America/Los_Angeles" \
--session isolated \
--message "Summarize overnight updates." \
--announce \
--channel slack \
--to "channel:C1234567890"
```
مهمة معزولة مع تجاوز للنموذج والتفكير:
```bash
openclaw cron add \
--name "Deep analysis" \
--cron "0 6 * * 1" \
--tz "America/Los_Angeles" \
--session isolated \
--message "Weekly deep analysis of project progress." \
--model "opus" \
--thinking high \
--announce
```
## Webhooks
يمكن لـ Gateway كشف نقاط نهاية HTTP webhook للمشغلات الخارجية. فعّل ذلك في الإعدادات:
```json5
{
hooks: {
enabled: true,
token: "shared-secret",
path: "/hooks",
},
}
```
### المصادقة
يجب أن يتضمن كل طلب رمز hook عبر ترويسة:
- `Authorization: Bearer <token>` (موصى به)
- `x-openclaw-token: <token>`
يتم رفض الرموز في سلسلة الاستعلام.
### POST /hooks/wake
أضف حدث نظام إلى قائمة انتظار الجلسة الرئيسية:
```bash
curl -X POST http://127.0.0.1:18789/hooks/wake \
-H 'Authorization: Bearer SECRET' \
-H 'Content-Type: application/json' \
-d '{"text":"New email received","mode":"now"}'
```
- `text` (مطلوب): وصف الحدث
- `mode` (اختياري): `now` (الافتراضي) أو `next-heartbeat`
### POST /hooks/agent
شغّل دورة وكيل معزولة:
```bash
curl -X POST http://127.0.0.1:18789/hooks/agent \
-H 'Authorization: Bearer SECRET' \
-H 'Content-Type: application/json' \
-d '{"message":"Summarize inbox","name":"Email","model":"openai/gpt-5.4-mini"}'
```
الحقول: `message` (مطلوب)، `name`، `agentId`، `wakeMode`، `deliver`، `channel`، `to`، `model`، `thinking`، `timeoutSeconds`.
### Hooks المعينة (POST /hooks/\<name\>)
تُحل أسماء hooks المخصصة عبر `hooks.mappings` في الإعدادات. ويمكن للتعيينات تحويل الحمولات العشوائية إلى إجراءات `wake` أو `agent` باستخدام قوالب أو تحويلات برمجية.
### الأمان
- أبقِ نقاط نهاية hook خلف local loopback أو tailnet أو reverse proxy موثوق.
- استخدم رمز hook مخصصًا؛ لا تعِد استخدام رموز مصادقة gateway.
- أبقِ `hooks.path` على مسار فرعي مخصص؛ يتم رفض `/`.
- اضبط `hooks.allowedAgentIds` لتقييد التوجيه الصريح لـ `agentId`.
- أبقِ `hooks.allowRequestSessionKey=false` ما لم تكن تحتاج إلى جلسات يحددها المتصل.
- إذا فعّلت `hooks.allowRequestSessionKey`، فاضبط أيضًا `hooks.allowedSessionKeyPrefixes` لتقييد أشكال مفاتيح الجلسات المسموح بها.
- تُغلَّف حمولات hook بحدود أمان افتراضيًا.
## تكامل Gmail PubSub
اربط مشغلات صندوق وارد Gmail بـ OpenClaw عبر Google PubSub.
**المتطلبات المسبقة**: CLI `gcloud`، و`gog` (`gogcli`)، وhooks مفعلة في OpenClaw، وTailscale لنقطة النهاية العامة عبر HTTPS.
### إعداد المعالج (موصى به)
```bash
openclaw webhooks gmail setup --account openclaw@gmail.com
```
يكتب هذا إعداد `hooks.gmail`، ويفعّل الإعداد المسبق لـ Gmail، ويستخدم Tailscale Funnel لنقطة نهاية الدفع.
### التشغيل التلقائي لـ Gateway
عندما يكون `hooks.enabled=true` و`hooks.gmail.account` مضبوطًا، يبدأ Gateway تشغيل `gog gmail watch serve` عند الإقلاع ويجدد المراقبة تلقائيًا. اضبط `OPENCLAW_SKIP_GMAIL_WATCHER=1` لإلغاء الاشتراك.
### إعداد يدوي لمرة واحدة
1. حدّد مشروع GCP الذي يملك عميل OAuth المستخدم بواسطة `gog`:
```bash
gcloud auth login
gcloud config set project <project-id>
gcloud services enable gmail.googleapis.com pubsub.googleapis.com
```
2. أنشئ topic وامنح Gmail صلاحية دفع النشر:
```bash
gcloud pubsub topics create gog-gmail-watch
gcloud pubsub topics add-iam-policy-binding gog-gmail-watch \
--member=serviceAccount:gmail-api-push@system.gserviceaccount.com \
--role=roles/pubsub.publisher
```
3. ابدأ المراقبة:
```bash
gog gmail watch start \
--account openclaw@gmail.com \
--label INBOX \
--topic projects/<project-id>/topics/gog-gmail-watch
```
### تجاوز نموذج Gmail
```json5
{
hooks: {
gmail: {
model: "openrouter/meta-llama/llama-3.3-70b-instruct:free",
thinking: "off",
},
},
}
```
## إدارة المهام
```bash
# List all jobs
openclaw cron list
# Edit a job
openclaw cron edit <jobId> --message "Updated prompt" --model "opus"
# Force run a job now
openclaw cron run <jobId>
# Run only if due
openclaw cron run <jobId> --due
# View run history
openclaw cron runs --id <jobId> --limit 50
# Delete a job
openclaw cron remove <jobId>
# Agent selection (multi-agent setups)
openclaw cron add --name "Ops sweep" --cron "0 6 * * *" --session isolated --message "Check ops queue" --agent ops
openclaw cron edit <jobId> --clear-agent
```
ملاحظة حول تجاوز النموذج:
- يغيّر `openclaw cron add|edit --model ...` النموذج المحدد للمهمة.
- إذا كان النموذج مسموحًا، يصل هذا المزوّد/النموذج المحدد نفسه إلى تشغيل الوكيل المعزول.
- إذا لم يكن مسموحًا، يحذّر cron ويعود إلى اختيار نموذج الوكيل/الافتراضي للمهمة.
- تظل سلاسل التراجع المهيأة مطبقة، لكن تجاوز `--model` العادي من دون قائمة تراجع صريحة لكل مهمة لم يعد ينتقل إلى النموذج الأساسي للوكيل باعتباره هدف إعادة محاولة إضافيًا صامتًا.
## الإعدادات
```json5
{
cron: {
enabled: true,
store: "~/.openclaw/cron/jobs.json",
maxConcurrentRuns: 1,
retry: {
maxAttempts: 3,
backoffMs: [60000, 120000, 300000],
retryOn: ["rate_limit", "overloaded", "network", "server_error"],
},
webhookToken: "replace-with-dedicated-webhook-token",
sessionRetention: "24h",
runLog: { maxBytes: "2mb", keepLines: 2000 },
},
}
```
تعطيل cron: `cron.enabled: false` أو `OPENCLAW_SKIP_CRON=1`.
**إعادة محاولة التشغيل الواحد**: تتم إعادة المحاولة للأخطاء المؤقتة (حد المعدل، والتحميل الزائد، والشبكة، وخطأ الخادم) حتى 3 مرات مع تراجع أُسّي. أما الأخطاء الدائمة فتؤدي إلى التعطيل فورًا.
**إعادة محاولة المهام المتكررة**: تراجع أُسّي (من 30 ثانية إلى 60 دقيقة) بين المحاولات. ويُعاد ضبط التراجع بعد التشغيل الناجح التالي.
**الصيانة**: يقوم `cron.sessionRetention` (الافتراضي `24h`) بتقليم إدخالات جلسات التشغيل المعزولة. كما يقوم `cron.runLog.maxBytes` / `cron.runLog.keepLines` بتقليم ملفات سجل التشغيل تلقائيًا.
## استكشاف الأخطاء وإصلاحها
### تسلسل الأوامر
```bash
openclaw status
openclaw gateway status
openclaw cron status
openclaw cron list
openclaw cron runs --id <jobId> --limit 20
openclaw system heartbeat last
openclaw logs --follow
openclaw doctor
```
### Cron لا يعمل
- تحقّق من `cron.enabled` ومتغير البيئة `OPENCLAW_SKIP_CRON`.
- أكّد أن Gateway يعمل بشكل مستمر.
- بالنسبة لجداول `cron`، تحقّق من المنطقة الزمنية (`--tz`) مقارنة بالمنطقة الزمنية للمضيف.
- تعني `reason: not-due` في مخرجات التشغيل أنه تم التحقق من التشغيل اليدوي باستخدام `openclaw cron run <jobId> --due` وأن المهمة لم يحن موعدها بعد.
### تم تشغيل Cron لكن لم يحدث تسليم
- يعني وضع التسليم `none` أنه لا يُتوقع إرسال أي رسالة خارجية.
- يعني غياب/عدم صحة هدف التسليم (`channel`/`to`) أنه تم تخطي الإرسال الخارجي.
- تعني أخطاء مصادقة القناة (`unauthorized` و`Forbidden`) أن التسليم تم حجبه بواسطة بيانات الاعتماد.
- إذا أعاد التشغيل المعزول فقط الرمز الصامت (`NO_REPLY` / `no_reply`)،
فإن OpenClaw يحجب التسليم الخارجي المباشر ويحجب أيضًا مسار
الملخص الاحتياطي الموضوع في قائمة الانتظار، لذلك لا يُنشر أي شيء إلى الدردشة.
- بالنسبة للمهام المعزولة المملوكة لـ cron، لا تتوقع من الوكيل استخدام أداة الرسائل
كحل احتياطي. فالمشغّل يملك التسليم النهائي؛ ويبقي `--no-deliver` التشغيل
داخليًا بدلًا من السماح بإرسال مباشر.
### ملاحظات مهمة حول المنطقة الزمنية
- يستخدم Cron بدون `--tz` المنطقة الزمنية لمضيف gateway.
- تُعامل جداول `at` التي لا تحتوي على منطقة زمنية على أنها UTC.
- يستخدم `activeHours` في heartbeat تحليل المنطقة الزمنية المهيأ.
## ذو صلة
- [الأتمتة والمهام](/automation) — لمحة سريعة عن جميع آليات الأتمتة
- [المهام الخلفية](/automation/tasks) — سجل المهام لتنفيذات cron
- [Heartbeat](/gateway/heartbeat) — دورات الجلسة الرئيسية الدورية
- [المنطقة الزمنية](/concepts/timezone) — إعداد المنطقة الزمنية

15
docs/ar/automation/cron-vs-heartbeat.md Normal file
View File

@ -0,0 +1,15 @@
---
summary: إعادة التوجيه إلى /automation
title: Cron مقابل Heartbeat
x-i18n:
generated_at: "2026-04-05T12:33:54Z"
model: gpt-5.4
provider: openai
source_hash: 579c6618108ad7e2a71f53d5d6aa6550956fa0fdb2fe64ecdb7e8a0ce1366e33
source_path: automation/cron-vs-heartbeat.md
workflow: 15
---
# Cron مقابل Heartbeat
انتقلت هذه الصفحة إلى [Automation & Tasks](/automation). راجع [Automation & Tasks](/automation) للاطلاع على دليل القرار الذي يقارن بين cron وheartbeat.

15
docs/ar/automation/gmail-pubsub.md Normal file
View File

@ -0,0 +1,15 @@
---
summary: إعادة توجيه إلى /automation/cron-jobs
title: Gmail PubSub
x-i18n:
generated_at: "2026-04-05T12:33:55Z"
model: gpt-5.4
provider: openai
source_hash: c2e17fdc8c09d52b6dc9fb6c44053446f07d02c65a0ab725d4ea038bd035d889
source_path: automation/gmail-pubsub.md
workflow: 15
---
# Gmail PubSub
تم نقل هذه الصفحة إلى [المهام المجدولة](/automation/cron-jobs#gmail-pubsub-integration). راجع [المهام المجدولة](/automation/cron-jobs#gmail-pubsub-integration) للاطلاع على توثيق Gmail PubSub.

310
docs/ar/automation/hooks.md Normal file
View File

@ -0,0 +1,310 @@
---
read_when:
- تريد أتمتة قائمة على الأحداث لأوامر /new و/reset و/stop وأحداث دورة حياة الوكيل
- تريد إنشاء الخطافات أو تثبيتها أو تصحيحها
summary: 'الخطافات: أتمتة قائمة على الأحداث للأوامر وأحداث دورة الحياة'
title: الخطافات
x-i18n:
generated_at: "2026-04-05T12:34:28Z"
model: gpt-5.4
provider: openai
source_hash: 66eb75bb2b3b2ad229bf3da24fdb0fe021ed08f812fd1d13c69b3bd9df0218e5
source_path: automation/hooks.md
workflow: 15
---
# الخطافات
الخطافات هي نصوص برمجية صغيرة تعمل عندما يحدث شيء ما داخل Gateway. يتم اكتشافها تلقائيًا من الأدلة ويمكن فحصها باستخدام `openclaw hooks`.
هناك نوعان من الخطافات في OpenClaw:
- **الخطافات الداخلية** (هذه الصفحة): تعمل داخل Gateway عند حدوث أحداث الوكيل، مثل `/new` أو `/reset` أو `/stop` أو أحداث دورة الحياة.
- **Webhooks**: نقاط نهاية HTTP خارجية تتيح للأنظمة الأخرى تشغيل العمل في OpenClaw. راجع [Webhooks](/automation/cron-jobs#webhooks).
يمكن أيضًا تضمين الخطافات داخل plugins. يعرض `openclaw hooks list` كلًا من الخطافات المستقلة والخطافات التي تديرها plugins.
## البدء السريع
```bash
# List available hooks
openclaw hooks list
# Enable a hook
openclaw hooks enable session-memory
# Check hook status
openclaw hooks check
# Get detailed information
openclaw hooks info session-memory
```
## أنواع الأحداث
| الحدث | وقت تشغيله |
| ------------------------ | ---------------------------------------------- |
| `command:new` | عند إصدار الأمر `/new` |
| `command:reset` | عند إصدار الأمر `/reset` |
| `command:stop` | عند إصدار الأمر `/stop` |
| `command` | أي حدث أمر (مستمع عام) |
| `session:compact:before` | قبل أن يلخص الضغط السجل |
| `session:compact:after` | بعد اكتمال الضغط |
| `session:patch` | عند تعديل خصائص الجلسة |
| `agent:bootstrap` | قبل إدخال ملفات التمهيد الخاصة بمساحة العمل |
| `gateway:startup` | بعد بدء القنوات وتحميل الخطافات |
| `message:received` | رسالة واردة من أي قناة |
| `message:transcribed` | بعد اكتمال نسخ الصوت |
| `message:preprocessed` | بعد اكتمال فهم جميع الوسائط والروابط |
| `message:sent` | تم تسليم الرسالة الصادرة |
## كتابة الخطافات
### بنية الخطاف
كل خطاف عبارة عن دليل يحتوي على ملفين:
```
my-hook/
├── HOOK.md # Metadata + documentation
└── handler.ts # Handler implementation
```
### تنسيق HOOK.md
```markdown
---
name: my-hook
description: "Short description of what this hook does"
metadata:
{ "openclaw": { "emoji": "🔗", "events": ["command:new"], "requires": { "bins": ["node"] } } }
---
# My Hook
Detailed documentation goes here.
```
**حقول Metadata** (`metadata.openclaw`):
| الحقل | الوصف |
| ---------- | ----------------------------------------------------- |
| `emoji` | رمز تعبيري للعرض في CLI |
| `events` | مصفوفة بالأحداث المطلوب الاستماع إليها |
| `export` | التصدير المسمى المطلوب استخدامه (الافتراضي `"default"`) |
| `os` | المنصات المطلوبة (مثل `["darwin", "linux"]`) |
| `requires` | مسارات `bins` أو `anyBins` أو `env` أو `config` المطلوبة |
| `always` | تجاوز فحوصات الأهلية (قيمة منطقية) |
| `install` | طرق التثبيت |
### تنفيذ المعالج
```typescript
const handler = async (event) => {
if (event.type !== "command" || event.action !== "new") {
return;
}
console.log(`[my-hook] New command triggered`);
// Your logic here
// Optionally send message to user
event.messages.push("Hook executed!");
};
export default handler;
```
يتضمن كل حدث: `type` و`action` و`sessionKey` و`timestamp` و`messages` (استخدم push لإرسالها إلى المستخدم) و`context` (بيانات خاصة بالحدث).
### أبرز عناصر سياق الحدث
**أحداث الأوامر** (`command:new`, `command:reset`): ‏`context.sessionEntry` و`context.previousSessionEntry` و`context.commandSource` و`context.workspaceDir` و`context.cfg`.
**أحداث الرسائل** (`message:received`): ‏`context.from` و`context.content` و`context.channelId` و`context.metadata` (بيانات خاصة بالمزوّد تتضمن `senderId` و`senderName` و`guildId`).
**أحداث الرسائل** (`message:sent`): ‏`context.to` و`context.content` و`context.success` و`context.channelId`.
**أحداث الرسائل** (`message:transcribed`): ‏`context.transcript` و`context.from` و`context.channelId` و`context.mediaPath`.
**أحداث الرسائل** (`message:preprocessed`): ‏`context.bodyForAgent` (النص النهائي المُثْرى) و`context.from` و`context.channelId`.
**أحداث التمهيد** (`agent:bootstrap`): ‏`context.bootstrapFiles` (مصفوفة قابلة للتعديل) و`context.agentId`.
**أحداث تصحيح الجلسة** (`session:patch`): ‏`context.sessionEntry` و`context.patch` (الحقول المتغيرة فقط) و`context.cfg`. يمكن فقط للعملاء ذوي الامتيازات تشغيل أحداث التصحيح.
**أحداث الضغط**: يتضمن `session:compact:before` القيمتين `messageCount` و`tokenCount`. ويضيف `session:compact:after` القيم `compactedCount` و`summaryLength` و`tokensBefore` و`tokensAfter`.
## اكتشاف الخطافات
يتم اكتشاف الخطافات من هذه الأدلة، بترتيب تصاعدي لأولوية التجاوز:
1. **الخطافات المضمّنة**: تأتي مع OpenClaw
2. **خطافات plugins**: خطافات مضمّنة داخل plugins المثبتة
3. **الخطافات المُدارة**: ‏`~/.openclaw/hooks/` (مثبتة من المستخدم، ومشتركة بين مساحات العمل). تشترك الأدلة الإضافية من `hooks.internal.load.extraDirs` في هذه الأولوية.
4. **خطافات مساحة العمل**: ‏`<workspace>/hooks/` (لكل وكيل، ومعطّلة افتراضيًا حتى يتم تفعيلها صراحة)
يمكن لخطافات مساحة العمل إضافة أسماء خطافات جديدة، لكنها لا يمكنها تجاوز الخطافات المضمّنة أو المُدارة أو المقدمة من plugin بالاسم نفسه.
### حزم الخطافات
حزم الخطافات هي حزم npm تصدّر الخطافات عبر `openclaw.hooks` في `package.json`. ثبّتها باستخدام:
```bash
openclaw plugins install <path-or-spec>
```
تكون مواصفات npm من السجل فقط (اسم الحزمة مع إصدار دقيق اختياري أو dist-tag). يتم رفض مواصفات Git/URL/file ونطاقات semver.
## الخطافات المضمّنة
| الخطاف | الأحداث | ما الذي يفعله |
| --------------------- | ------------------------------ | ----------------------------------------------------- |
| session-memory | `command:new`, `command:reset` | يحفظ سياق الجلسة في `<workspace>/memory/` |
| bootstrap-extra-files | `agent:bootstrap` | يدرج ملفات تمهيد إضافية من أنماط glob |
| command-logger | `command` | يسجل جميع الأوامر في `~/.openclaw/logs/commands.log` |
| boot-md | `gateway:startup` | يشغّل `BOOT.md` عند بدء gateway |
لتفعيل أي خطاف مضمّن:
```bash
openclaw hooks enable <hook-name>
```
### تفاصيل session-memory
يستخرج آخر 15 رسالة مستخدم/مساعد، وينشئ slug وصفيًا لاسم الملف عبر LLM، ويحفظه في `<workspace>/memory/YYYY-MM-DD-slug.md`. يتطلب تكوين `workspace.dir`.
### إعداد bootstrap-extra-files
```json
{
"hooks": {
"internal": {
"entries": {
"bootstrap-extra-files": {
"enabled": true,
"paths": ["packages/*/AGENTS.md", "packages/*/TOOLS.md"]
}
}
}
}
}
```
تُحلّ المسارات نسبةً إلى مساحة العمل. يتم تحميل أسماء ملفات التمهيد الأساسية المعترف بها فقط (`AGENTS.md` و`SOUL.md` و`TOOLS.md` و`IDENTITY.md` و`USER.md` و`HEARTBEAT.md` و`BOOTSTRAP.md` و`MEMORY.md`).
## خطافات plugins
يمكن لـ plugins تسجيل خطافات من خلال Plugin SDK من أجل تكامل أعمق: اعتراض استدعاءات الأدوات، وتعديل المطالبات، والتحكم في تدفق الرسائل، وغير ذلك. يوفّر Plugin SDK عدد 28 خطافًا تغطي تحليل النموذج، ودورة حياة الوكيل، وتدفق الرسائل، وتنفيذ الأدوات، وتنسيق الوكلاء الفرعيين، ودورة حياة gateway.
للاطلاع على المرجع الكامل لخطافات plugin بما في ذلك `before_tool_call` و`before_agent_reply` و`before_install` وجميع خطافات plugin الأخرى، راجع [Plugin Architecture](/plugins/architecture#provider-runtime-hooks).
## التكوين
```json
{
"hooks": {
"internal": {
"enabled": true,
"entries": {
"session-memory": { "enabled": true },
"command-logger": { "enabled": false }
}
}
}
}
```
متغيرات البيئة لكل خطاف:
```json
{
"hooks": {
"internal": {
"entries": {
"my-hook": {
"enabled": true,
"env": { "MY_CUSTOM_VAR": "value" }
}
}
}
}
}
```
أدلة خطافات إضافية:
```json
{
"hooks": {
"internal": {
"load": {
"extraDirs": ["/path/to/more/hooks"]
}
}
}
}
```
<Note>
لا تزال صيغة التكوين القديمة للمصفوفة `hooks.internal.handlers` مدعومة للتوافق مع الإصدارات السابقة، لكن يجب أن تستخدم الخطافات الجديدة النظام القائم على الاكتشاف.
</Note>
## مرجع CLI
```bash
# List all hooks (add --eligible, --verbose, or --json)
openclaw hooks list
# Show detailed info about a hook
openclaw hooks info <hook-name>
# Show eligibility summary
openclaw hooks check
# Enable/disable
openclaw hooks enable <hook-name>
openclaw hooks disable <hook-name>
```
## أفضل الممارسات
- **أبقِ المعالجات سريعة.** تعمل الخطافات أثناء معالجة الأوامر. نفّذ الأعمال الثقيلة بشكل fire-and-forget باستخدام `void processInBackground(event)`.
- **تعامل مع الأخطاء بسلاسة.** لف العمليات المحفوفة بالمخاطر داخل try/catch؛ ولا تُطلق الأخطاء حتى تتمكن المعالجات الأخرى من العمل.
- **قم بتصفية الأحداث مبكرًا.** أعد فورًا إذا لم يكن نوع الحدث/الإجراء ذا صلة.
- **استخدم مفاتيح أحداث محددة.** فضّل `"events": ["command:new"]` على `"events": ["command"]` لتقليل الحمل.
## استكشاف الأخطاء وإصلاحها
### لم يتم اكتشاف الخطاف
```bash
# Verify directory structure
ls -la ~/.openclaw/hooks/my-hook/
# Should show: HOOK.md, handler.ts
# List all discovered hooks
openclaw hooks list
```
### الخطاف غير مؤهل
```bash
openclaw hooks info my-hook
```
تحقق من الثنائيات المفقودة (PATH) أو متغيرات البيئة أو قيم التكوين أو توافق نظام التشغيل.
### الخطاف لا يتم تنفيذه
1. تحقق من أن الخطاف مفعّل: `openclaw hooks list`
2. أعد تشغيل عملية gateway حتى تُعاد تحميل الخطافات.
3. تحقق من سجلات gateway: ‏`./scripts/clawlog.sh | grep hook`
## ذو صلة
- [مرجع CLI: hooks](/cli/hooks)
- [Webhooks](/automation/cron-jobs#webhooks)
- [Plugin Architecture](/plugins/architecture#provider-runtime-hooks) — المرجع الكامل لخطافات plugin
- [Configuration](/gateway/configuration-reference#hooks)

122
docs/ar/automation/index.md Normal file
View File

@ -0,0 +1,122 @@
---
read_when:
- عند تحديد كيفية أتمتة العمل باستخدام OpenClaw
- عند الاختيار بين heartbeat، وcron، وhooks، والأوامر الدائمة
- عند البحث عن نقطة الدخول المناسبة للأتمتة
summary: 'نظرة عامة على آليات الأتمتة: المهام، وcron، وhooks، والأوامر الدائمة، وTask Flow'
title: الأتمتة والمهام
x-i18n:
generated_at: "2026-04-05T12:34:21Z"
model: gpt-5.4
provider: openai
source_hash: 13cd05dcd2f38737f7bb19243ad1136978bfd727006fd65226daa3590f823afe
source_path: automation/index.md
workflow: 15
---
# الأتمتة والمهام
يشغّل OpenClaw العمل في الخلفية من خلال المهام، والوظائف المجدولة، وhooks الأحداث، والتعليمات الدائمة. تساعدك هذه الصفحة على اختيار الآلية المناسبة وفهم كيفية ترابطها.
## دليل اتخاذ القرار السريع
```mermaid
flowchart TD
START([What do you need?]) --> Q1{Schedule work?}
START --> Q2{Track detached work?}
START --> Q3{Orchestrate multi-step flows?}
START --> Q4{React to lifecycle events?}
START --> Q5{Give the agent persistent instructions?}
Q1 -->|Yes| Q1a{Exact timing or flexible?}
Q1a -->|Exact| CRON["Scheduled Tasks (Cron)"]
Q1a -->|Flexible| HEARTBEAT[Heartbeat]
Q2 -->|Yes| TASKS[Background Tasks]
Q3 -->|Yes| FLOW[Task Flow]
Q4 -->|Yes| HOOKS[Hooks]
Q5 -->|Yes| SO[Standing Orders]
```
| حالة الاستخدام | الخيار الموصى به | السبب |
| -------------- | ---------------- | ------ |
| إرسال تقرير يومي في تمام الساعة 9 صباحًا | Scheduled Tasks (Cron) | توقيت دقيق، وتنفيذ معزول |
| ذكّرني بعد 20 دقيقة | Scheduled Tasks (Cron) | تشغيل لمرة واحدة مع توقيت دقيق (`--at`) |
| تشغيل تحليل عميق أسبوعي | Scheduled Tasks (Cron) | مهمة مستقلة، ويمكنها استخدام نموذج مختلف |
| فحص البريد الوارد كل 30 دقيقة | Heartbeat | يجمّع مع فحوصات أخرى، ومدرك للسياق |
| مراقبة التقويم للأحداث القادمة | Heartbeat | ملائم بطبيعته للوعي الدوري |
| فحص حالة وكيل فرعي أو تشغيل ACP | Background Tasks | يسجّل دفتر المهام كل العمل المنفصل |
| تدقيق ما الذي تم تشغيله ومتى | Background Tasks | `openclaw tasks list` و`openclaw tasks audit` |
| بحث متعدد الخطوات ثم تلخيص | Task Flow | تنسيق دائم مع تتبع المراجعات |
| تشغيل برنامج نصي عند إعادة تعيين الجلسة | Hooks | يعتمد على الأحداث، ويعمل عند أحداث دورة الحياة |
| تنفيذ تعليمات برمجية عند كل استدعاء أداة | Hooks | يمكن لـ Hooks التصفية حسب نوع الحدث |
| التحقق دائمًا من الامتثال قبل الرد | Standing Orders | تُحقن تلقائيًا في كل جلسة |
### Scheduled Tasks (Cron) مقابل Heartbeat
| البعد | Scheduled Tasks (Cron) | Heartbeat |
| ----- | ---------------------- | --------- |
| التوقيت | دقيق (تعبيرات cron، تشغيل لمرة واحدة) | تقريبي (افتراضيًا كل 30 دقيقة) |
| سياق الجلسة | جديد (معزول) أو مشترك | سياق الجلسة الرئيسية الكامل |
| سجلات المهام | يتم إنشاؤها دائمًا | لا يتم إنشاؤها أبدًا |
| التسليم | قناة، أو webhook، أو بصمت | مضمّن داخل الجلسة الرئيسية |
| الأنسب لـ | التقارير، والتذكيرات، والوظائف الخلفية | فحوصات البريد الوارد، والتقويم، والإشعارات |
استخدم Scheduled Tasks (Cron) عندما تحتاج إلى توقيت دقيق أو تنفيذ معزول. واستخدم Heartbeat عندما يستفيد العمل من سياق الجلسة الكامل ويكون التوقيت التقريبي كافيًا.
## المفاهيم الأساسية
### المهام المجدولة (cron)
يمثل Cron المجدول المدمج في Gateway للتوقيت الدقيق. فهو يحتفظ بالوظائف، ويوقظ الوكيل في الوقت المناسب، ويمكنه تسليم المخرجات إلى قناة دردشة أو نقطة نهاية webhook. ويدعم التذكيرات التي تعمل لمرة واحدة، والتعبيرات المتكررة، ومشغلات webhook الواردة.
راجع [Scheduled Tasks](/automation/cron-jobs).
### المهام
يتتبع دفتر المهام الخلفية جميع الأعمال المنفصلة: عمليات تشغيل ACP، وتشغيل الوكلاء الفرعيين، وتنفيذات cron المعزولة، وعمليات CLI. المهام هي سجلات وليست مجدولات. استخدم `openclaw tasks list` و`openclaw tasks audit` لفحصها.
راجع [Background Tasks](/automation/tasks).
### Task Flow
يمثل Task Flow طبقة تنسيق التدفقات فوق المهام الخلفية. وهو يدير التدفقات الدائمة متعددة الخطوات مع أوضاع المزامنة المُدارة والمنعكسة، وتتبع المراجعات، و`openclaw tasks flow list|show|cancel` للفحص.
راجع [Task Flow](/automation/taskflow).
### الأوامر الدائمة
تمنح الأوامر الدائمة الوكيل صلاحية تشغيل دائمة للبرامج المحددة. وهي توجد في ملفات مساحة العمل (عادةً `AGENTS.md`) وتُحقن في كل جلسة. ويمكن دمجها مع cron لفرض التنفيذ المعتمد على الوقت.
راجع [Standing Orders](/automation/standing-orders).
### Hooks
تمثل Hooks برامج نصية تعتمد على الأحداث ويتم تشغيلها بواسطة أحداث دورة حياة الوكيل (`/new` و`/reset` و`/stop`) وضغط الجلسة، وبدء تشغيل البوابة، وتدفق الرسائل، واستدعاءات الأدوات. يتم اكتشاف Hooks تلقائيًا من الأدلة ويمكن إدارتها باستخدام `openclaw hooks`.
راجع [Hooks](/automation/hooks).
### Heartbeat
يمثل Heartbeat دورًا دوريًا للجلسة الرئيسية (افتراضيًا كل 30 دقيقة). وهو يجمّع عدة فحوصات (البريد الوارد، والتقويم، والإشعارات) في دور وكيل واحد مع سياق الجلسة الكامل. ولا تنشئ أدوار Heartbeat سجلات مهام. استخدم `HEARTBEAT.md` لقائمة تحقق صغيرة، أو كتلة `tasks:` عندما تريد فحوصات دورية مستحقة فقط داخل heartbeat نفسه. تتخطى ملفات heartbeat الفارغة كـ `empty-heartbeat-file`، ويتخطى وضع المهام المستحقة فقط كـ `no-tasks-due`.
راجع [Heartbeat](/gateway/heartbeat).
## كيف تعمل معًا
- **Cron** يتعامل مع الجداول الدقيقة (التقارير اليومية، والمراجعات الأسبوعية) والتذكيرات التي تعمل لمرة واحدة. جميع تنفيذات cron تنشئ سجلات مهام.
- **Heartbeat** يتعامل مع المراقبة الروتينية (البريد الوارد، والتقويم، والإشعارات) في دور مجمّع واحد كل 30 دقيقة.
- **Hooks** تتفاعل مع أحداث محددة (استدعاءات الأدوات، وإعادة تعيين الجلسة، والضغط) عبر برامج نصية مخصصة.
- **الأوامر الدائمة** تمنح الوكيل سياقًا مستمرًا وحدودًا للصلاحيات.
- **Task Flow** ينسق التدفقات متعددة الخطوات فوق المهام الفردية.
- **المهام** تتتبع تلقائيًا كل الأعمال المنفصلة حتى تتمكن من فحصها وتدقيقها.
## ذو صلة
- [Scheduled Tasks](/automation/cron-jobs) — الجدولة الدقيقة والتذكيرات التي تعمل لمرة واحدة
- [Background Tasks](/automation/tasks) — دفتر المهام لجميع الأعمال المنفصلة
- [Task Flow](/automation/taskflow) — تنسيق التدفقات الدائمة متعددة الخطوات
- [Hooks](/automation/hooks) — برامج نصية لدورة الحياة تعتمد على الأحداث
- [Standing Orders](/automation/standing-orders) — تعليمات الوكيل الدائمة
- [Heartbeat](/gateway/heartbeat) — أدوار دورية للجلسة الرئيسية
- [Configuration Reference](/gateway/configuration-reference) — جميع مفاتيح الإعداد

15
docs/ar/automation/poll.md Normal file
View File

@ -0,0 +1,15 @@
---
summary: إعادة التوجيه إلى /tools/message
title: استطلاعات الرأي
x-i18n:
generated_at: "2026-04-05T12:33:56Z"
model: gpt-5.4
provider: openai
source_hash: 8d69432ad8ba5fd80b59f8df779a1105ce0a2ff767d7dd5dc9d8e3ac1cb1ff1f
source_path: automation/poll.md
workflow: 15
---
# استطلاعات الرأي
انتقلت هذه الصفحة إلى [أداة الرسائل](/cli/message). راجع [أداة الرسائل](/cli/message) للاطلاع على وثائق استطلاعات الرأي.

261
docs/ar/automation/standing-orders.md Normal file
View File

@ -0,0 +1,261 @@
---
read_when:
- عند إعداد مهام سير عمل لوكلاء ذاتيين تعمل من دون مطالبة لكل مهمة
- عند تحديد ما الذي يمكن للوكيل فعله بشكل مستقل مقابل ما يحتاج إلى موافقة بشرية
- عند تنظيم وكلاء متعددَي البرامج بحدود واضحة وقواعد تصعيد
summary: تحديد سلطة تشغيل دائمة لبرامج الوكلاء الذاتيين
title: الأوامر الدائمة
x-i18n:
generated_at: "2026-04-05T12:34:25Z"
model: gpt-5.4
provider: openai
source_hash: 81347d7a51a6ce20e6493277afee92073770f69a91a2e6b3bf87b99bb586d038
source_path: automation/standing-orders.md
workflow: 15
---
# الأوامر الدائمة
تمنح الأوامر الدائمة وكيلك **سلطة تشغيل دائمة** للبرامج المحددة. وبدلًا من إعطاء تعليمات لكل مهمة على حدة في كل مرة، فإنك تعرّف برامج ذات نطاق واضح ومشغلات وقواعد تصعيد — وينفذ الوكيل العمل ذاتيًا ضمن تلك الحدود.
وهذا هو الفرق بين أن تقول لمساعدك "أرسل التقرير الأسبوعي" كل يوم جمعة، وبين منحه سلطة دائمة: "أنت مسؤول عن التقرير الأسبوعي. اجمعه كل يوم جمعة، وأرسله، ولا تصعّد إلا إذا بدا أن هناك شيئًا غير صحيح."
## لماذا الأوامر الدائمة؟
**من دون أوامر دائمة:**
- يجب عليك مطالبة الوكيل بكل مهمة
- يظل الوكيل في وضع خمول بين الطلبات
- يُنسى العمل الروتيني أو يتأخر
- تصبح أنت عنق الزجاجة
**مع الأوامر الدائمة:**
- ينفذ الوكيل العمل ذاتيًا ضمن حدود محددة
- يتم إنجاز العمل الروتيني في موعده من دون مطالبة
- لا تتدخل إلا في الاستثناءات وحالات الموافقة
- يستثمر الوكيل وقت الخمول بشكل منتج
## كيف تعمل
تُعرَّف الأوامر الدائمة في ملفات [مساحة عمل الوكيل](/concepts/agent-workspace) الخاصة بك. والنهج الموصى به هو تضمينها مباشرةً في `AGENTS.md` (الذي يُحقن تلقائيًا في كل جلسة) حتى تكون دائمًا ضمن سياق الوكيل. وبالنسبة إلى الإعدادات الأكبر، يمكنك أيضًا وضعها في ملف مخصص مثل `standing-orders.md` والإشارة إليه من `AGENTS.md`.
يحدد كل برنامج ما يلي:
1. **النطاق** — ما الذي يملك الوكيل صلاحية القيام به
2. **المشغلات** — متى يتم التنفيذ (جدول زمني أو حدث أو شرط)
3. **بوابات الموافقة** — ما الذي يتطلب اعتمادًا بشريًا قبل التنفيذ
4. **قواعد التصعيد** — متى يجب التوقف وطلب المساعدة
يحمّل الوكيل هذه التعليمات في كل جلسة عبر ملفات تمهيد مساحة العمل (راجع [مساحة عمل الوكيل](/concepts/agent-workspace) للحصول على القائمة الكاملة للملفات المحقونة تلقائيًا) وينفذ وفقًا لها، مع دمجها مع [مهام cron](/automation/cron-jobs) لفرض التنفيذ المعتمد على الوقت.
<Tip>
ضع الأوامر الدائمة في `AGENTS.md` لضمان تحميلها في كل جلسة. يقوم تمهيد مساحة العمل تلقائيًا بحقن `AGENTS.md` و`SOUL.md` و`TOOLS.md` و`IDENTITY.md` و`USER.md` و`HEARTBEAT.md` و`BOOTSTRAP.md` و`MEMORY.md` — لكنه لا يحقن الملفات العشوائية داخل الأدلة الفرعية.
</Tip>
## مكونات الأمر الدائم
```markdown
## Program: Weekly Status Report
**Authority:** Compile data, generate report, deliver to stakeholders
**Trigger:** Every Friday at 4 PM (enforced via cron job)
**Approval gate:** None for standard reports. Flag anomalies for human review.
**Escalation:** If data source is unavailable or metrics look unusual (>2σ from norm)
### Execution Steps
1. Pull metrics from configured sources
2. Compare to prior week and targets
3. Generate report in Reports/weekly/YYYY-MM-DD.md
4. Deliver summary via configured channel
5. Log completion to Agent/Logs/
### What NOT to Do
- Do not send reports to external parties
- Do not modify source data
- Do not skip delivery if metrics look bad — report accurately
```
## الأوامر الدائمة + مهام Cron
تحدد الأوامر الدائمة **ما الذي** يملك الوكيل صلاحية فعله. وتحدد [مهام Cron](/automation/cron-jobs) **متى** يحدث ذلك. وهما يعملان معًا:
```
Standing Order: "You own the daily inbox triage"
↓
Cron Job (8 AM daily): "Execute inbox triage per standing orders"
↓
Agent: Reads standing orders → executes steps → reports results
```
يجب أن تشير رسالة مهمة cron إلى الأمر الدائم بدلًا من تكراره:
```bash
openclaw cron add \
--name daily-inbox-triage \
--cron "0 8 * * 1-5" \
--tz America/New_York \
--timeout-seconds 300 \
--announce \
--channel bluebubbles \
--to "+1XXXXXXXXXX" \
--message "Execute daily inbox triage per standing orders. Check mail for new alerts. Parse, categorize, and persist each item. Report summary to owner. Escalate unknowns."
```
## أمثلة
### المثال 1: المحتوى ووسائل التواصل الاجتماعي (دورة أسبوعية)
```markdown
## Program: Content & Social Media
**Authority:** Draft content, schedule posts, compile engagement reports
**Approval gate:** All posts require owner review for first 30 days, then standing approval
**Trigger:** Weekly cycle (Monday review → mid-week drafts → Friday brief)
### Weekly Cycle
- **Monday:** Review platform metrics and audience engagement
- **Tuesday–Thursday:** Draft social posts, create blog content
- **Friday:** Compile weekly marketing brief → deliver to owner
### Content Rules
- Voice must match the brand (see SOUL.md or brand voice guide)
- Never identify as AI in public-facing content
- Include metrics when available
- Focus on value to audience, not self-promotion
```
### المثال 2: العمليات المالية (تعمل بالمحفزات الحدثية)
```markdown
## Program: Financial Processing
**Authority:** Process transaction data, generate reports, send summaries
**Approval gate:** None for analysis. Recommendations require owner approval.
**Trigger:** New data file detected OR scheduled monthly cycle
### When New Data Arrives
1. Detect new file in designated input directory
2. Parse and categorize all transactions
3. Compare against budget targets
4. Flag: unusual items, threshold breaches, new recurring charges
5. Generate report in designated output directory
6. Deliver summary to owner via configured channel
### Escalation Rules
- Single item > $500: immediate alert
- Category > budget by 20%: flag in report
- Unrecognizable transaction: ask owner for categorization
- Failed processing after 2 retries: report failure, do not guess
```
### المثال 3: المراقبة والتنبيهات (مستمرة)
```markdown
## Program: System Monitoring
**Authority:** Check system health, restart services, send alerts
**Approval gate:** Restart services automatically. Escalate if restart fails twice.
**Trigger:** Every heartbeat cycle
### Checks
- Service health endpoints responding
- Disk space above threshold
- Pending tasks not stale (>24 hours)
- Delivery channels operational
### Response Matrix
| Condition | Action | Escalate? |
| ---------------- | ------------------------ | ------------------------ |
| Service down | Restart automatically | Only if restart fails 2x |
| Disk space < 10% | Alert owner | Yes |
| Stale task > 24h | Remind owner | No |
| Channel offline | Log and retry next cycle | If offline > 2 hours |
```
## نمط التنفيذ-التحقق-الإبلاغ
تعمل الأوامر الدائمة بأفضل شكل عند دمجها مع انضباط صارم في التنفيذ. يجب أن تتبع كل مهمة في أمر دائم هذه الحلقة:
1. **التنفيذ** — نفّذ العمل الفعلي (لا تكتفِ بالإقرار بالتعليمات)
2. **التحقق** — أكّد أن النتيجة صحيحة (الملف موجود، الرسالة تم تسليمها، البيانات جرى تحليلها)
3. **الإبلاغ** — أخبر المالك بما تم إنجازه وما الذي تم التحقق منه
```markdown
### Execution Rules
- Every task follows Execute-Verify-Report. No exceptions.
- "I'll do that" is not execution. Do it, then report.
- "Done" without verification is not acceptable. Prove it.
- If execution fails: retry once with adjusted approach.
- If still fails: report failure with diagnosis. Never silently fail.
- Never retry indefinitely — 3 attempts max, then escalate.
```
يمنع هذا النمط أكثر أوضاع فشل الوكلاء شيوعًا: الإقرار بالمهمة من دون إكمالها.
## بنية متعددة البرامج
بالنسبة إلى الوكلاء الذين يديرون عدة مجالات، نظّم الأوامر الدائمة كبرامج منفصلة ذات حدود واضحة:
```markdown
# Standing Orders
## Program 1: [Domain A] (Weekly)
...
## Program 2: [Domain B] (Monthly + On-Demand)
...
## Program 3: [Domain C] (As-Needed)
...
## Escalation Rules (All Programs)
- [Common escalation criteria]
- [Approval gates that apply across programs]
```
يجب أن يكون لكل برنامج:
- **وتيرة تشغيل** خاصة به (أسبوعية، شهرية، مدفوعة بالأحداث، مستمرة)
- **بوابات موافقة** خاصة به (بعض البرامج تحتاج إلى إشراف أكبر من غيرها)
- **حدود** واضحة (يجب أن يعرف الوكيل أين ينتهي برنامج ويبدأ آخر)
## أفضل الممارسات
### افعل
- ابدأ بسلطة محدودة ووسّعها مع بناء الثقة
- حدّد بوابات موافقة صريحة للإجراءات عالية المخاطر
- أدرج أقسام "ما الذي لا يجب فعله" — فالحدود مهمة بقدر أهمية الأذونات
- ادمجها مع مهام cron لتنفيذ موثوق معتمد على الوقت
- راجع سجلات الوكيل أسبوعيًا للتحقق من الالتزام بالأوامر الدائمة
- حدّث الأوامر الدائمة مع تطور احتياجاتك — فهي وثائق حية
### تجنب
- منح سلطة واسعة من اليوم الأول ("افعل ما تراه أفضل")
- تجاوز قواعد التصعيد — كل برنامج يحتاج إلى بند "متى تتوقف وتسأل"
- افتراض أن الوكيل سيتذكر التعليمات الشفهية — ضع كل شيء في الملف
- خلط المجالات في برنامج واحد — برامج منفصلة لمجالات منفصلة
- نسيان فرض التنفيذ باستخدام مهام cron — فالأوامر الدائمة من دون مشغلات تصبح مجرد اقتراحات
## ذو صلة
- [الأتمتة والمهام](/automation) — نظرة شاملة على جميع آليات الأتمتة
- [مهام Cron](/automation/cron-jobs) — فرض الجدولة للأوامر الدائمة
- [Hooks](/automation/hooks) — نصوص برمجية مدفوعة بالأحداث لأحداث دورة حياة الوكيل
- [Webhooks](/automation/cron-jobs#webhooks) — مشغلات أحداث HTTP واردة
- [مساحة عمل الوكيل](/concepts/agent-workspace) — المكان الذي تعيش فيه الأوامر الدائمة، بما في ذلك القائمة الكاملة لملفات التمهيد المحقونة تلقائيًا (`AGENTS.md` و`SOUL.md` وغيرها)

89
docs/ar/automation/taskflow.md Normal file
View File

@ -0,0 +1,89 @@
---
read_when:
- تريد فهم كيفية ارتباط Task Flow بالمهام الخلفية
- تصادف Task Flow أو openclaw tasks flow في ملاحظات الإصدار أو المستندات
- تريد فحص حالة التدفق المستدامة أو إدارتها
summary: طبقة تنسيق التدفقات Task Flow فوق المهام الخلفية
title: Task Flow
x-i18n:
generated_at: "2026-04-05T12:34:14Z"
model: gpt-5.4
provider: openai
source_hash: 172871206b839845db807d9c627015890f7733b862e276853d5dbfbe29e03883
source_path: automation/taskflow.md
workflow: 15
---
# Task Flow
Task Flow هي البنية الأساسية لتنسيق التدفقات التي تقع فوق [المهام الخلفية](/automation/tasks). وهي تدير تدفقات مستدامة متعددة الخطوات لها حالتها الخاصة، وتتبع المراجعات، ودلالات المزامنة، بينما تظل المهام الفردية هي وحدة العمل المنفصل.
## متى تستخدم Task Flow
استخدم Task Flow عندما يمتد العمل عبر خطوات متسلسلة متعددة أو متفرعة وتحتاج إلى تتبع مستدام للتقدم عبر عمليات إعادة تشغيل البوابة. بالنسبة إلى العمليات الخلفية المفردة، تكون [المهمة](/automation/tasks) العادية كافية.
| السيناريو | الاستخدام |
| ------------------------------------ | -------------------- |
| مهمة خلفية واحدة | مهمة عادية |
| مسار متعدد الخطوات (A ثم B ثم C) | Task Flow (مُدارة) |
| مراقبة المهام المُنشأة خارجيًا | Task Flow (معكوسة) |
| تذكير لمرة واحدة | مهمة Cron |
## أوضاع المزامنة
### الوضع المُدار
تتولى Task Flow دورة الحياة من البداية إلى النهاية. فهي تنشئ المهام كخطوات للتدفق، وتدفعها إلى الاكتمال، وتُقدّم حالة التدفق تلقائيًا.
مثال: تدفق تقرير أسبوعي يقوم (1) بجمع البيانات، و(2) بإنشاء التقرير، و(3) بتسليمه. تنشئ Task Flow كل خطوة كمهمة خلفية، وتنتظر اكتمالها، ثم تنتقل إلى الخطوة التالية.
```
Flow: weekly-report
Step 1: gather-data → task created → succeeded
Step 2: generate-report → task created → succeeded
Step 3: deliver → task created → running
```
### الوضع المعكوس
تراقب Task Flow المهام المُنشأة خارجيًا وتحافظ على مزامنة حالة التدفق من دون تولي مسؤولية إنشاء المهام. يكون هذا مفيدًا عندما تنشأ المهام من مهام Cron أو أوامر CLI أو مصادر أخرى وتريد عرضًا موحدًا لتقدمها كتدفق.
مثال: ثلاث مهام Cron مستقلة تشكّل معًا روتين "عمليات الصباح". يتتبع التدفق المعكوس تقدمها الجماعي من دون التحكم في وقت تشغيلها أو كيفية تشغيلها.
## الحالة المستدامة وتتبع المراجعات
يحفظ كل تدفق حالته الخاصة ويتتبع المراجعات بحيث يستمر التقدم عبر عمليات إعادة تشغيل البوابة. ويتيح تتبع المراجعات اكتشاف التعارضات عندما تحاول مصادر متعددة تقديم التدفق نفسه بالتزامن.
## سلوك الإلغاء
يضبط `openclaw tasks flow cancel` نية إلغاء ثابتة على التدفق. تُلغى المهام النشطة داخل التدفق، ولا تبدأ أي خطوات جديدة. تستمر نية الإلغاء عبر عمليات إعادة التشغيل، لذا يظل التدفق المُلغى مُلغًى حتى إذا أُعيد تشغيل البوابة قبل انتهاء جميع المهام الفرعية.
## أوامر CLI
```bash
# List active and recent flows
openclaw tasks flow list
# Show details for a specific flow
openclaw tasks flow show <lookup>
# Cancel a running flow and its active tasks
openclaw tasks flow cancel <lookup>
```
| الأمر | الوصف |
| --------------------------------- | --------------------------------------------- |
| `openclaw tasks flow list` | يعرض التدفقات المتتبعة مع الحالة ووضع المزامنة |
| `openclaw tasks flow show <id>` | يفحص تدفقًا واحدًا حسب معرّف التدفق أو مفتاح البحث |
| `openclaw tasks flow cancel <id>` | يُلغي تدفقًا قيد التشغيل ومهامه النشطة |
## كيف ترتبط التدفقات بالمهام
تنسّق التدفقات المهام، ولا تستبدلها. قد يقود تدفق واحد عدة مهام خلفية خلال مدة عمله. استخدم `openclaw tasks` لفحص سجلات المهام الفردية، واستخدم `openclaw tasks flow` لفحص التدفق المنسِّق.
## ذو صلة
- [المهام الخلفية](/automation/tasks) — سجل العمل المنفصل الذي تنسقه التدفقات
- [CLI: tasks](/cli/index#tasks) — مرجع أوامر CLI لـ `openclaw tasks flow`
- [نظرة عامة على الأتمتة](/automation) — جميع آليات الأتمتة في لمحة
- [مهام Cron](/automation/cron-jobs) — الوظائف المجدولة التي قد تتدفق إلى التدفقات

330
docs/ar/automation/tasks.md Normal file
View File

@ -0,0 +1,330 @@
---
read_when:
- فحص العمل الجاري في الخلفية أو الذي اكتمل مؤخرًا
- تصحيح أخطاء فشل التسليم لتشغيلات الوكيل المنفصلة
- فهم كيفية ارتباط التشغيلات في الخلفية بالجلسات وcron وheartbeat
summary: تتبّع المهام في الخلفية لتشغيلات ACP، والوكلاء الفرعيين، ووظائف cron المعزولة، وعمليات CLI
title: المهام في الخلفية
x-i18n:
generated_at: "2026-04-05T12:34:43Z"
model: gpt-5.4
provider: openai
source_hash: 6c95ccf4388d07e60a7bb68746b161793f4bb5ff2ba3d5ce9e51f2225dab2c4d
source_path: automation/tasks.md
workflow: 15
---
# المهام في الخلفية
> **هل تبحث عن الجدولة؟** راجع [Automation & Tasks](/automation) لاختيار الآلية المناسبة. تغطي هذه الصفحة **تتبّع** العمل في الخلفية، وليس جدولته.
تتتبّع المهام في الخلفية العمل الذي يُشغَّل **خارج جلسة المحادثة الرئيسية**:
تشغيلات ACP، وإنشاء الوكلاء الفرعيين، وتنفيذات وظائف cron المعزولة، والعمليات التي تبدأ عبر CLI.
لا تحل المهام محل الجلسات أو وظائف cron أو heartbeat، بل هي **سجل النشاط** الذي يدوّن ما الذي حدث في العمل المنفصل، ومتى حدث، وما إذا كان قد نجح.
<Note>
ليس كل تشغيل وكيل ينشئ مهمة. أدوار heartbeat والدردشة التفاعلية العادية لا تفعل ذلك. أما جميع تنفيذات cron، وعمليات إنشاء ACP، وعمليات إنشاء الوكلاء الفرعيين، وأوامر وكيل CLI فتنشئ مهام.
</Note>
## ملخص سريع
- المهام هي **سجلات** وليست مجدولات — يحدد cron وheartbeat _متى_ يُشغَّل العمل، بينما تتتبّع المهام _ما الذي حدث_.
- تنشئ ACP، والوكلاء الفرعيون، وجميع وظائف cron، وعمليات CLI مهام. أدوار heartbeat لا تفعل ذلك.
- تنتقل كل مهمة عبر `queued → running → terminal` (succeeded أو failed أو timed_out أو cancelled أو lost).
- تبقى مهام cron نشطة ما دام وقت تشغيل cron لا يزال يملك الوظيفة؛ وتبقى مهام CLI المعتمدة على الدردشة نشطة فقط ما دام سياق التشغيل المالك لها لا يزال فعالًا.
- يعتمد الإكمال على الدفع: يمكن للعمل المنفصل الإخطار مباشرة أو إيقاظ
جلسة الطالب/heartbeat عند انتهائه، لذلك تكون حلقات استطلاع الحالة عادةً
نهجًا غير مناسب.
- تنظّف تشغيلات cron المعزولة وإكمالات الوكلاء الفرعيين، على أساس أفضل جهد، علامات تبويب/عمليات المتصفح المتتبَّعة لجلسة الابن قبل إنهاء أعمال التنظيف النهائية.
- يمنع تسليم cron المعزول الردود المرحلية القديمة من الأصل أثناء
استمرار تصريف عمل الوكيل الفرعي المنحدر، ويفضّل المخرجات النهائية للفرع
المنحدر عندما تصل قبل التسليم.
- تُسلَّم إشعارات الإكمال مباشرة إلى قناة أو تُدرج في الطابور لنبضة heartbeat التالية.
- يعرض `openclaw tasks list` جميع المهام؛ ويكشف `openclaw tasks audit` المشكلات.
- تُحتفظ السجلات النهائية لمدة 7 أيام، ثم تُحذف تلقائيًا.
## بدء سريع
```bash
# عرض جميع المهام (الأحدث أولًا)
openclaw tasks list
# التصفية حسب وقت التشغيل أو الحالة
openclaw tasks list --runtime acp
openclaw tasks list --status running
# عرض تفاصيل مهمة محددة (بالمعرف أو معرّف التشغيل أو مفتاح الجلسة)
openclaw tasks show <lookup>
# إلغاء مهمة قيد التشغيل (يُنهي جلسة الابن)
openclaw tasks cancel <lookup>
# تغيير سياسة الإشعارات لمهمة
openclaw tasks notify <lookup> state_changes
# تشغيل تدقيق صحي
openclaw tasks audit
# معاينة الصيانة أو تطبيقها
openclaw tasks maintenance
openclaw tasks maintenance --apply
# فحص حالة TaskFlow
openclaw tasks flow list
openclaw tasks flow show <lookup>
openclaw tasks flow cancel <lookup>
```
## ما الذي ينشئ مهمة
| المصدر | نوع وقت التشغيل | متى يُنشأ سجل المهمة | سياسة الإشعار الافتراضية |
| ---------------------- | --------------- | ----------------------------------------------------- | ------------------------ |
| تشغيلات ACP في الخلفية | `acp` | عند إنشاء جلسة ACP فرعية | `done_only` |
| تنسيق الوكلاء الفرعيين | `subagent` | عند إنشاء وكيل فرعي عبر `sessions_spawn` | `done_only` |
| وظائف cron (كل الأنواع) | `cron` | كل تنفيذ cron (في الجلسة الرئيسية والمعزول) | `silent` |
| عمليات CLI | `cli` | أوامر `openclaw agent` التي تعمل عبر gateway | `silent` |
تستخدم مهام cron في الجلسة الرئيسية سياسة الإشعار `silent` افتراضيًا — فهي تنشئ سجلات للتتبّع لكنها لا تولّد إشعارات. كما تستخدم مهام cron المعزولة `silent` افتراضيًا أيضًا، لكنها أوضح ظهورًا لأنها تعمل في جلستها الخاصة.
**ما الذي لا ينشئ مهام:**
- أدوار heartbeat — الجلسة الرئيسية؛ راجع [Heartbeat](/gateway/heartbeat)
- أدوار الدردشة التفاعلية العادية
- استجابات `/command` المباشرة
## دورة حياة المهمة
```mermaid
stateDiagram-v2
[*] --> queued
queued --> running : agent starts
running --> succeeded : completes ok
running --> failed : error
running --> timed_out : timeout exceeded
running --> cancelled : operator cancels
queued --> lost : session gone > 5 min
running --> lost : session gone > 5 min
```
| الحالة | ما الذي تعنيه |
| ----------- | ------------------------------------------------------------------------ |
| `queued` | أُنشئت وتنتظر بدء الوكيل |
| `running` | يجري تنفيذ دور الوكيل حاليًا |
| `succeeded` | اكتملت بنجاح |
| `failed` | اكتملت مع حدوث خطأ |
| `timed_out` | تجاوزت المهلة المكوّنة |
| `cancelled` | أوقفها المشغّل عبر `openclaw tasks cancel` |
| `lost` | فقد وقت التشغيل حالة الدعم الموثوقة بعد فترة سماح مدتها 5 دقائق |
تحدث الانتقالات تلقائيًا — فعندما ينتهي تشغيل الوكيل المرتبط، تتحدّث حالة المهمة لتطابقه.
تكون `lost` واعية بوقت التشغيل:
- مهام ACP: اختفت بيانات جلسة ACP الفرعية الداعمة.
- مهام الوكيل الفرعي: اختفت الجلسة الفرعية الداعمة من مخزن الوكيل المستهدف.
- مهام cron: لم يعد وقت تشغيل cron يتتبّع الوظيفة بوصفها نشطة.
- مهام CLI: تستخدم مهام الجلسة الفرعية المعزولة جلسة الابن؛ بينما تستخدم مهام CLI المعتمدة على الدردشة سياق التشغيل النشط مباشرة، لذلك لا تُبقي صفوف جلسات القناة/المجموعة/المباشرة العالقة هذه المهام نشطة.
## التسليم والإشعارات
عندما تصل مهمة إلى حالة نهائية، يقوم OpenClaw بإخطارك. توجد مساران للتسليم:
**التسليم المباشر** — إذا كان للمهمة هدف قناة (أي `requesterOrigin`)، تنتقل رسالة الإكمال مباشرة إلى تلك القناة (Telegram أو Discord أو Slack، وغير ذلك). بالنسبة إلى إكمالات الوكيل الفرعي، يحافظ OpenClaw أيضًا على توجيه السلسلة/الموضوع المرتبط عند توفره، ويمكنه ملء قيمة `to` أو الحساب المفقود من المسار المخزَّن في جلسة الطالب (`lastChannel` / `lastTo` / `lastAccountId`) قبل التخلي عن التسليم المباشر.
**التسليم المدرج في طابور الجلسة** — إذا فشل التسليم المباشر أو لم يُضبط أصل، يُدرج التحديث كحدث نظام في جلسة الطالب ويظهر عند heartbeat التالية.
<Tip>
يؤدي اكتمال المهمة إلى تشغيل إيقاظ heartbeat فوري حتى ترى النتيجة بسرعة — لا تحتاج إلى انتظار نبضة heartbeat المجدولة التالية.
</Tip>
هذا يعني أن سير العمل المعتاد يعتمد على الدفع: ابدأ العمل المنفصل مرة واحدة، ثم دع
وقت التشغيل يوقظك أو يخطرك عند الإكمال. لا تستطلع حالة المهمة إلا عندما
تحتاج إلى تصحيح الأخطاء أو التدخل أو إجراء تدقيق صريح.
### سياسات الإشعار
تحكّم في مقدار ما تتلقاه من كل مهمة:
| السياسة | ما الذي يُسلَّم |
| --------------------- | ----------------------------------------------------------------------- |
| `done_only` (افتراضي) | الحالة النهائية فقط (مثل succeeded وfailed وغيرها) — **وهذا هو الافتراضي** |
| `state_changes` | كل انتقال حالة وتحديث تقدّم |
| `silent` | لا شيء على الإطلاق |
غيّر السياسة أثناء تشغيل المهمة:
```bash
openclaw tasks notify <lookup> state_changes
```
## مرجع CLI
### `tasks list`
```bash
openclaw tasks list [--runtime <acp|subagent|cron|cli>] [--status <status>] [--json]
```
أعمدة المخرجات: معرّف المهمة، والنوع، والحالة، والتسليم، ومعرّف التشغيل، وجلسة الابن، والملخص.
### `tasks show`
```bash
openclaw tasks show <lookup>
```
يقبل رمز البحث معرّف مهمة، أو معرّف تشغيل، أو مفتاح جلسة. ويعرض السجل الكامل بما في ذلك التوقيت، وحالة التسليم، والخطأ، والملخص النهائي.
### `tasks cancel`
```bash
openclaw tasks cancel <lookup>
```
بالنسبة إلى مهام ACP والوكيل الفرعي، يؤدي هذا إلى إنهاء جلسة الابن. وتنتقل الحالة إلى `cancelled` ويُرسل إشعار بالتسليم.
### `tasks notify`
```bash
openclaw tasks notify <lookup> <done_only|state_changes|silent>
```
### `tasks audit`
```bash
openclaw tasks audit [--json]
```
يكشف عن المشكلات التشغيلية. كما تظهر النتائج في `openclaw status` عند اكتشاف مشكلات.
| النتيجة | الشدة | المحفّز |
| ------------------------ | ------ | ------------------------------------------------------ |
| `stale_queued` | warn | بقيت في الانتظار لأكثر من 10 دقائق |
| `stale_running` | error | بقيت قيد التشغيل لأكثر من 30 دقيقة |
| `lost` | error | اختفت ملكية المهمة المدعومة من وقت التشغيل |
| `delivery_failed` | warn | فشل التسليم وسياسة الإشعار ليست `silent` |
| `missing_cleanup` | warn | مهمة نهائية من دون طابع زمني للتنظيف |
| `inconsistent_timestamps`| warn | مخالفة في الخط الزمني (مثل الانتهاء قبل البدء) |
### `tasks maintenance`
```bash
openclaw tasks maintenance [--json]
openclaw tasks maintenance --apply [--json]
```
استخدم هذا لمعاينة أو تطبيق التسوية، ووضع طابع التنظيف، والحذف
للمهام وحالة Task Flow.
التسوية واعية بوقت التشغيل:
- تتحقق مهام ACP/الوكيل الفرعي من جلسة الابن الداعمة.
- تتحقق مهام cron مما إذا كان وقت تشغيل cron لا يزال يملك الوظيفة.
- تتحقق مهام CLI المعتمدة على الدردشة من سياق التشغيل النشط المالك، وليس فقط صف جلسة الدردشة.
كما أن تنظيف الإكمال واعٍ بوقت التشغيل:
- يحاول إكمال الوكيل الفرعي، على أساس أفضل جهد، إغلاق علامات تبويب/عمليات المتصفح المتتبَّعة لجلسة الابن قبل متابعة إعلان التنظيف.
- يحاول إكمال cron المعزول، على أساس أفضل جهد، إغلاق علامات تبويب/عمليات المتصفح المتتبَّعة لجلسة cron قبل أن يُفكك التشغيل بالكامل.
- ينتظر تسليم cron المعزول متابعة الوكيل الفرعي المنحدر عند الحاجة،
ويمنع نص الإقرار الأصلي القديم بدلًا من الإعلان عنه.
- يفضّل تسليم إكمال الوكيل الفرعي أحدث نص مرئي للمساعد؛ وإذا كان فارغًا يعود إلى نص tool/toolResult الأحدث بعد تنقيته، ويمكن أن تُختصر تشغيلات استدعاء الأدوات التي انتهت بالمهلة فقط إلى ملخص قصير للتقدّم الجزئي.
- لا تحجب إخفاقات التنظيف النتيجة الحقيقية للمهمة.
### `tasks flow list|show|cancel`
```bash
openclaw tasks flow list [--status <status>] [--json]
openclaw tasks flow show <lookup> [--json]
openclaw tasks flow cancel <lookup>
```
استخدم هذه الأوامر عندما يكون Task Flow المنسِّق هو ما يهمك
بدلًا من سجل مهمة واحدة في الخلفية.
## لوحة مهام الدردشة (`/tasks`)
استخدم `/tasks` في أي جلسة دردشة لرؤية المهام في الخلفية المرتبطة بتلك الجلسة. تعرض اللوحة
المهام النشطة والتي اكتملت مؤخرًا مع وقت التشغيل والحالة والتوقيت وتفاصيل التقدّم أو الخطأ.
عندما لا تحتوي الجلسة الحالية على مهام مرتبطة مرئية، يعود `/tasks` إلى أعداد المهام المحلية للوكيل
حتى تحصل على نظرة عامة من دون كشف تفاصيل الجلسات الأخرى.
للحصول على سجل المشغّل الكامل، استخدم CLI: `openclaw tasks list`.
## التكامل مع الحالة (ضغط المهام)
يتضمن `openclaw status` ملخصًا سريعًا للمهام:
```
Tasks: 3 queued · 2 running · 1 issues
```
يعرض الملخص:
- **active** — عدد `queued` + `running`
- **failures** — عدد `failed` + `timed_out` + `lost`
- **byRuntime** — تفصيل حسب `acp` و`subagent` و`cron` و`cli`
يستخدم كل من `/status` وأداة `session_status` لقطة مهام واعية بالتنظيف: تُفضَّل المهام النشطة،
وتُخفى الصفوف المكتملة القديمة، ولا تظهر الإخفاقات الحديثة إلا عندما لا يبقى عمل نشط.
وهذا يُبقي بطاقة الحالة مركّزة على ما يهم الآن.
## التخزين والصيانة
### مكان وجود المهام
تُحفَظ سجلات المهام في SQLite في:
```
$OPENCLAW_STATE_DIR/tasks/runs.sqlite
```
يُحمَّل السجل إلى الذاكرة عند بدء gateway، وتُزامَن الكتابات إلى SQLite لضمان الاستمرارية عبر عمليات إعادة التشغيل.
### الصيانة التلقائية
يعمل منظّف كل **60 ثانية** ويتعامل مع ثلاثة أمور:
1. **التسوية** — يتحقق مما إذا كانت المهام النشطة لا تزال تملك دعمًا موثوقًا من وقت التشغيل. تستخدم مهام ACP/الوكيل الفرعي حالة الجلسة الفرعية، وتستخدم مهام cron ملكية الوظيفة النشطة، وتستخدم مهام CLI المعتمدة على الدردشة سياق التشغيل المالك. إذا اختفت حالة الدعم هذه لأكثر من 5 دقائق، تُعلَّم المهمة بأنها `lost`.
2. **وضع طابع التنظيف** — يضبط طابعًا زمنيًا `cleanupAfter` على المهام النهائية (`endedAt + 7 days`).
3. **الحذف** — يحذف السجلات التي تجاوزت تاريخ `cleanupAfter` الخاص بها.
**مدة الاحتفاظ**: تُحتفظ سجلات المهام النهائية لمدة **7 أيام**، ثم تُحذف تلقائيًا. لا حاجة إلى أي إعداد.
## كيف ترتبط المهام بالأنظمة الأخرى
### المهام وTask Flow
[Task Flow](/automation/taskflow) هي طبقة تنسيق التدفق فوق المهام في الخلفية. قد ينسّق تدفق واحد عدة مهام خلال عمره باستخدام أوضاع المزامنة المُدارة أو المعكوسة. استخدم `openclaw tasks` لفحص سجلات المهام الفردية و`openclaw tasks flow` لفحص التدفق المنسِّق.
راجع [Task Flow](/automation/taskflow) للتفاصيل.
### المهام وcron
يعيش **تعريف** وظيفة cron في `~/.openclaw/cron/jobs.json`. ينشئ **كل** تنفيذ cron سجل مهمة — سواء في الجلسة الرئيسية أو بشكل معزول. تستخدم مهام cron في الجلسة الرئيسية سياسة الإشعار `silent` افتراضيًا حتى تتتبّع من دون توليد إشعارات.
راجع [وظائف Cron](/automation/cron-jobs).
### المهام وheartbeat
تشغيلات heartbeat هي أدوار جلسة رئيسية — ولا تنشئ سجلات مهام. وعندما تكتمل مهمة، يمكنها تشغيل إيقاظ heartbeat حتى ترى النتيجة بسرعة.
راجع [Heartbeat](/gateway/heartbeat).
### المهام والجلسات
قد تشير المهمة إلى `childSessionKey` (حيث يُشغَّل العمل) و`requesterSessionKey` (من بدأه). الجلسات هي سياق المحادثة؛ أما المهام فهي تتبّع النشاط فوق ذلك.
### المهام وتشغيلات الوكيل
يرتبط `runId` الخاص بالمهمة بتشغيل الوكيل الذي ينفّذ العمل. وتحدّث أحداث دورة حياة الوكيل (البدء، والانتهاء، والخطأ) حالة المهمة تلقائيًا — ولا تحتاج إلى إدارة دورة الحياة يدويًا.
## ذو صلة
- [Automation & Tasks](/automation) — جميع آليات الأتمتة في لمحة
- [Task Flow](/automation/taskflow) — تنسيق التدفق فوق المهام
- [المهام المجدولة](/automation/cron-jobs) — جدولة العمل في الخلفية
- [Heartbeat](/gateway/heartbeat) — أدوار الجلسة الرئيسية الدورية
- [CLI: Tasks](/cli/index#tasks) — مرجع أوامر CLI

15
docs/ar/automation/troubleshooting.md Normal file
View File

@ -0,0 +1,15 @@
---
summary: إعادة توجيه إلى /automation/cron-jobs
title: استكشاف أخطاء الأتمتة وإصلاحها
x-i18n:
generated_at: "2026-04-05T12:34:07Z"
model: gpt-5.4
provider: openai
source_hash: 6621342754fb56234b89e71167f73bad6c070273ff0b8d12dbb20854e32e7980
source_path: automation/troubleshooting.md
workflow: 15
---
# استكشاف أخطاء الأتمتة وإصلاحها
تم نقل هذه الصفحة إلى [المهام المجدولة](/automation/cron-jobs#troubleshooting). راجع [المهام المجدولة](/automation/cron-jobs#troubleshooting) للاطلاع على وثائق استكشاف الأخطاء وإصلاحها.

15
docs/ar/automation/webhook.md Normal file
View File

@ -0,0 +1,15 @@
---
summary: إعادة التوجيه إلى /automation/cron-jobs
title: Webhooks
x-i18n:
generated_at: "2026-04-05T12:34:09Z"
model: gpt-5.4
provider: openai
source_hash: 7511f6bc28e7f13ee1d9313bb5551825afb5706019068079603a44668c4dda34
source_path: automation/webhook.md
workflow: 15
---
# Webhooks
تم نقل هذه الصفحة إلى [المهام المجدولة](/automation/cron-jobs#webhooks). راجع [المهام المجدولة](/automation/cron-jobs#webhooks) للاطلاع على وثائق Webhooks.

110
docs/ar/brave-search.md Normal file
View File

@ -0,0 +1,110 @@
---
read_when:
- تريد استخدام Brave Search لـ `web_search`
- تحتاج إلى `BRAVE_API_KEY` أو تفاصيل الخطة
summary: إعداد Brave Search API لـ `web_search`
title: Brave Search (المسار القديم)
x-i18n:
generated_at: "2026-04-05T12:34:21Z"
model: gpt-5.4
provider: openai
source_hash: 7788e4cee7dc460819e55095c87df8cea29ba3a8bd3cef4c0e98ac601b45b651
source_path: brave-search.md
workflow: 15
---
# Brave Search API
يدعم OpenClaw واجهة Brave Search API باعتبارها موفّر `web_search`.
## الحصول على مفتاح API
1. أنشئ حساب Brave Search API على [https://brave.com/search/api/](https://brave.com/search/api/)
2. في لوحة التحكم، اختر خطة **Search** وأنشئ مفتاح API.
3. خزّن المفتاح في الإعدادات أو اضبط `BRAVE_API_KEY` في بيئة Gateway.
## مثال على الإعداد
```json5
{
plugins: {
entries: {
brave: {
config: {
webSearch: {
apiKey: "BRAVE_API_KEY_HERE",
mode: "web", // or "llm-context"
},
},
},
},
},
tools: {
web: {
search: {
provider: "brave",
maxResults: 5,
timeoutSeconds: 30,
},
},
},
}
```
توجد الآن إعدادات بحث Brave الخاصة بالموفّر ضمن `plugins.entries.brave.config.webSearch.*`.
ولا يزال `tools.web.search.apiKey` القديم يُحمَّل عبر طبقة التوافق، لكنه لم يعد مسار الإعداد القانوني.
يتحكم `webSearch.mode` في آلية النقل الخاصة بـ Brave:
- `web` (الافتراضي): بحث ويب عادي من Brave مع العناوين وعناوين URL والمقتطفات
- `llm-context`: واجهة Brave LLM Context API مع مقاطع نصية مستخرجة مسبقًا ومصادر للاستناد
## معلمات الأداة
| المعلمة | الوصف |
| ------------- | ------------------------------------------------------------------- |
| `query` | استعلام البحث (مطلوب) |
| `count` | عدد النتائج المطلوب إرجاعها (1-10، الافتراضي: 5) |
| `country` | رمز بلد ISO مكوّن من حرفين (مثل: "US" و"DE") |
| `language` | رمز لغة ISO 639-1 لنتائج البحث (مثل: "en" و"de" و"fr") |
| `search_lang` | رمز لغة البحث في Brave (مثل: `en` و`en-gb` و`zh-hans`) |
| `ui_lang` | رمز لغة ISO لعناصر واجهة المستخدم |
| `freshness` | عامل تصفية زمني: `day` (24 ساعة) أو `week` أو `month` أو `year` |
| `date_after` | النتائج المنشورة بعد هذا التاريخ فقط (YYYY-MM-DD) |
| `date_before` | النتائج المنشورة قبل هذا التاريخ فقط (YYYY-MM-DD) |
**أمثلة:**
```javascript
// Country and language-specific search
await web_search({
query: "renewable energy",
country: "DE",
language: "de",
});
// Recent results (past week)
await web_search({
query: "AI news",
freshness: "week",
});
// Date range search
await web_search({
query: "AI developments",
date_after: "2024-01-01",
date_before: "2024-06-30",
});
```
## ملاحظات
- يستخدم OpenClaw خطة Brave **Search**. إذا كان لديك اشتراك قديم (مثل الخطة المجانية الأصلية مع 2,000 استعلام شهريًا)، فسيظل صالحًا لكنه لا يتضمن الميزات الأحدث مثل LLM Context أو حدود المعدل الأعلى.
- تتضمن كل خطة Brave **رصيدًا مجانيًا بقيمة \$5 شهريًا** (يتجدد). وتبلغ تكلفة خطة Search مقدار \$5 لكل 1,000 طلب، لذلك يغطي الرصيد 1,000 استعلام شهريًا. اضبط حد الاستخدام في لوحة تحكم Brave لتجنب الرسوم غير المتوقعة. راجع [بوابة Brave API](https://brave.com/search/api/) للاطلاع على الخطط الحالية.
- تتضمن خطة Search نقطة نهاية LLM Context وحقوق استدلال الذكاء الاصطناعي. ويتطلب تخزين النتائج لتدريب النماذج أو ضبطها خطة تتضمن حقوق تخزين صريحة. راجع [شروط الخدمة](https://api-dashboard.search.brave.com/terms-of-service) الخاصة بـ Brave.
- يعيد وضع `llm-context` إدخالات مصدر مستندة بدلًا من شكل مقتطفات بحث الويب العادي.
- لا يدعم وضع `llm-context` كلاً من `ui_lang` و`freshness` و`date_after` و`date_before`.
- يجب أن يتضمن `ui_lang` وسمًا فرعيًا للمنطقة مثل `en-US`.
- تُخزَّن النتائج مؤقتًا لمدة 15 دقيقة افتراضيًا (يمكن ضبطها عبر `cacheTtlMinutes`).
راجع [أدوات الويب](/tools/web) للحصول على إعداد `web_search` الكامل.

441
docs/ar/channels/bluebubbles.md Normal file
View File

@ -0,0 +1,441 @@
---
read_when:
- إعداد قناة BlueBubbles
- استكشاف أخطاء اقتران webhook وإصلاحها
- تكوين iMessage على macOS
summary: iMessage عبر خادم BlueBubbles على macOS ‏(إرسال/استقبال REST، الكتابة، التفاعلات، الاقتران، الإجراءات المتقدمة).
title: BlueBubbles
x-i18n:
generated_at: "2026-04-05T12:35:11Z"
model: gpt-5.4
provider: openai
source_hash: ed8e59a165bdfb8fd794ee2ad6e4dacd44aa02d512312c5f2fd7d15f863380bb
source_path: channels/bluebubbles.md
workflow: 15
---
# BlueBubbles (REST على macOS)
الحالة: plugin مضمّن يتصل بخادم BlueBubbles على macOS عبر HTTP. **موصى به لتكامل iMessage** بسبب واجهة API الأغنى وسهولة الإعداد مقارنة بقناة imsg القديمة.
## plugin المضمّن
تتضمن إصدارات OpenClaw الحالية BlueBubbles، لذلك لا تحتاج الإصدارات المعبأة المعتادة إلى خطوة `openclaw plugins install` منفصلة.
## نظرة عامة
- يعمل على macOS عبر تطبيق BlueBubbles المساعد ([bluebubbles.app](https://bluebubbles.app)).
- الموصى به/المختبر: macOS Sequoia ‏(15). يعمل macOS Tahoe ‏(26)، لكن التحرير معطل حاليًا على Tahoe، وقد تُبلغ تحديثات أيقونات المجموعات عن النجاح لكنها لا تتزامن.
- يتصل OpenClaw به عبر واجهة REST API الخاصة به (`GET /api/v1/ping` و`POST /message/text` و`POST /chat/:id/*`).
- تصل الرسائل الواردة عبر webhooks؛ أما الردود الصادرة ومؤشرات الكتابة وإيصالات القراءة وtapbacks فهي استدعاءات REST.
- يتم استيعاب المرفقات والملصقات كوسائط واردة (وتُعرَض للوكيل عندما يكون ذلك ممكنًا).
- يعمل الاقتران/قائمة السماح بالطريقة نفسها كما في القنوات الأخرى (`/channels/pairing` وما إلى ذلك) باستخدام `channels.bluebubbles.allowFrom` + رموز الاقتران.
- تُعرَض التفاعلات كأحداث نظام تمامًا مثل Slack/Telegram بحيث يمكن للوكلاء "الإشارة" إليها قبل الرد.
- الميزات المتقدمة: التحرير، وإلغاء الإرسال، وسلاسل الردود، وتأثيرات الرسائل، وإدارة المجموعات.
## البدء السريع
1. ثبّت خادم BlueBubbles على جهاز Mac لديك (اتبع التعليمات على [bluebubbles.app/install](https://bluebubbles.app/install)).
2. في إعدادات BlueBubbles، فعّل web API وحدد كلمة مرور.
3. شغّل `openclaw onboard` وحدد BlueBubbles، أو قم بالتكوين يدويًا:
```json5
{
channels: {
bluebubbles: {
enabled: true,
serverUrl: "http://192.168.1.100:1234",
password: "example-password",
webhookPath: "/bluebubbles-webhook",
},
},
}
```
4. وجّه webhooks الخاصة بـ BlueBubbles إلى gateway لديك (مثال: `https://your-gateway-host:3000/bluebubbles-webhook?password=<password>`).
5. ابدأ تشغيل gateway؛ سيقوم بتسجيل معالج webhook وبدء الاقتران.
ملاحظة أمنية:
- احرص دائمًا على تعيين كلمة مرور لـ webhook.
- تكون مصادقة webhook مطلوبة دائمًا. يرفض OpenClaw طلبات BlueBubbles webhook ما لم تتضمن كلمة مرور/guid يطابق `channels.bluebubbles.password` (مثل `?password=<password>` أو `x-password`) بغض النظر عن بنية loopback/proxy.
- يتم التحقق من مصادقة كلمة المرور قبل قراءة/تحليل أجسام webhook الكاملة.
## إبقاء Messages.app نشطًا (إعدادات VM / بدون واجهة)
قد تنتهي بعض إعدادات macOS VM / التشغيل الدائم إلى أن يصبح Messages.app "خاملًا" (تتوقف الأحداث الواردة حتى يتم فتح التطبيق/إحضاره إلى المقدمة). أحد الحلول البسيطة هو **تحفيز Messages كل 5 دقائق** باستخدام AppleScript + LaunchAgent.
### 1) احفظ AppleScript
احفظ هذا باسم:
- `~/Scripts/poke-messages.scpt`
مثال على script ‏(غير تفاعلي؛ لا يسرق التركيز):
```applescript
try
tell application "Messages"
if not running then
launch
end if
-- Touch the scripting interface to keep the process responsive.
set _chatCount to (count of chats)
end tell
on error
-- Ignore transient failures (first-run prompts, locked session, etc).
end try
```
### 2) ثبّت LaunchAgent
احفظ هذا باسم:
- `~/Library/LaunchAgents/com.user.poke-messages.plist`
```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>com.user.poke-messages</string>
<key>ProgramArguments</key>
<array>
<string>/bin/bash</string>
<string>-lc</string>
<string>/usr/bin/osascript &quot;$HOME/Scripts/poke-messages.scpt&quot;</string>
</array>
<key>RunAtLoad</key>
<true/>
<key>StartInterval</key>
<integer>300</integer>
<key>StandardOutPath</key>
<string>/tmp/poke-messages.log</string>
<key>StandardErrorPath</key>
<string>/tmp/poke-messages.err</string>
</dict>
</plist>
```
ملاحظات:
- يعمل هذا **كل 300 ثانية** و**عند تسجيل الدخول**.
- قد يؤدي التشغيل الأول إلى ظهور مطالبات macOS **Automation** ‏(`osascript` → Messages). وافق عليها في جلسة المستخدم نفسها التي تشغّل LaunchAgent.
قم بتحميله:
```bash
launchctl unload ~/Library/LaunchAgents/com.user.poke-messages.plist 2>/dev/null || true
launchctl load ~/Library/LaunchAgents/com.user.poke-messages.plist
```
## الإعداد التفاعلي
يتوفر BlueBubbles في الإعداد التفاعلي:
```
openclaw onboard
```
يطلب المعالج ما يلي:
- **Server URL** ‏(مطلوب): عنوان خادم BlueBubbles ‏(مثلًا، `http://192.168.1.100:1234`)
- **Password** ‏(مطلوب): كلمة مرور API من إعدادات BlueBubbles Server
- **Webhook path** ‏(اختياري): القيمة الافتراضية هي `/bluebubbles-webhook`
- **DM policy**: ‏pairing أو allowlist أو open أو disabled
- **Allow list**: أرقام الهواتف أو عناوين البريد الإلكتروني أو أهداف الدردشة
يمكنك أيضًا إضافة BlueBubbles عبر CLI:
```
openclaw channels add bluebubbles --http-url http://192.168.1.100:1234 --password <password>
```
## التحكم في الوصول (الرسائل الخاصة + المجموعات)
الرسائل الخاصة:
- الافتراضي: `channels.bluebubbles.dmPolicy = "pairing"`.
- يتلقى المرسلون غير المعروفين رمز اقتران؛ ويتم تجاهل الرسائل حتى الموافقة عليها (تنتهي صلاحية الرموز بعد ساعة واحدة).
- وافق عبر:
- `openclaw pairing list bluebubbles`
- `openclaw pairing approve bluebubbles <CODE>`
- الاقتران هو تبادل الرموز الافتراضي. التفاصيل: [الاقتران](/channels/pairing)
المجموعات:
- `channels.bluebubbles.groupPolicy = open | allowlist | disabled` ‏(الافتراضي: `allowlist`).
- يتحكم `channels.bluebubbles.groupAllowFrom` في من يمكنه التفعيل في المجموعات عندما يتم تعيين `allowlist`.
### إثراء أسماء جهات الاتصال (macOS، اختياري)
غالبًا ما تتضمن webhooks الخاصة بمجموعات BlueBubbles عناوين المشاركين الخام فقط. إذا كنت تريد أن يُظهر سياق `GroupMembers` أسماء جهات الاتصال المحلية بدلًا من ذلك، فيمكنك الاشتراك في إثراء Contacts المحلي على macOS:
- يؤدي `channels.bluebubbles.enrichGroupParticipantsFromContacts = true` إلى تمكين البحث. الافتراضي: `false`.
- لا تعمل عمليات البحث إلا بعد أن يسمح وصول المجموعة وتفويض الأوامر وضبط الإشارات بمرور الرسالة.
- يتم إثراء المشاركين الهاتفيين غير المسمّين فقط.
- تبقى أرقام الهواتف الخام هي البديل عند عدم العثور على تطابق محلي.
```json5
{
channels: {
bluebubbles: {
enrichGroupParticipantsFromContacts: true,
},
},
}
```
### ضبط الإشارات (المجموعات)
يدعم BlueBubbles ضبط الإشارات للمحادثات الجماعية، بما يتطابق مع سلوك iMessage/WhatsApp:
- يستخدم `agents.list[].groupChat.mentionPatterns` (أو `messages.groupChat.mentionPatterns`) لاكتشاف الإشارات.
- عند تمكين `requireMention` لمجموعة، لا يرد الوكيل إلا عند الإشارة إليه.
- تتجاوز أوامر التحكم من المرسلين المصرح لهم ضبط الإشارات.
تكوين لكل مجموعة:
```json5
{
channels: {
bluebubbles: {
groupPolicy: "allowlist",
groupAllowFrom: ["+15555550123"],
groups: {
"*": { requireMention: true }, // الافتراضي لجميع المجموعات
"iMessage;-;chat123": { requireMention: false }, // تجاوز لمجموعة محددة
},
},
},
}
```
### ضبط الأوامر
- تتطلب أوامر التحكم (مثل `/config` و`/model`) تفويضًا.
- يستخدم `allowFrom` و`groupAllowFrom` لتحديد تفويض الأوامر.
- يمكن للمرسلين المصرح لهم تشغيل أوامر التحكم حتى بدون إشارة في المجموعات.
## ارتباطات محادثات ACP
يمكن تحويل محادثات BlueBubbles إلى مساحات عمل ACP دائمة من دون تغيير طبقة النقل.
تدفق المشغل السريع:
- شغّل `/acp spawn codex --bind here` داخل الرسالة الخاصة أو الدردشة الجماعية المسموح بها.
- تُوجَّه الرسائل المستقبلية في محادثة BlueBubbles نفسها إلى جلسة ACP المنشأة.
- يعيد `/new` و`/reset` تعيين جلسة ACP المرتبطة نفسها في مكانها.
- يغلق `/acp close` جلسة ACP ويزيل الارتباط.
يتم أيضًا دعم الارتباطات الدائمة المكوّنة من خلال إدخالات `bindings[]` على المستوى الأعلى مع `type: "acp"` و`match.channel: "bluebubbles"`.
يمكن أن يستخدم `match.peer.id` أي صيغة هدف BlueBubbles مدعومة:
- مقبض DM مُطبَّع مثل `+15555550123` أو `user@example.com`
- `chat_id:<id>`
- `chat_guid:<guid>`
- `chat_identifier:<identifier>`
للحصول على ارتباطات مجموعات مستقرة، استخدم `chat_id:*` أو `chat_identifier:*` ويفضل ذلك.
مثال:
```json5
{
agents: {
list: [
{
id: "codex",
runtime: {
type: "acp",
acp: { agent: "codex", backend: "acpx", mode: "persistent" },
},
},
],
},
bindings: [
{
type: "acp",
agentId: "codex",
match: {
channel: "bluebubbles",
accountId: "default",
peer: { kind: "dm", id: "+15555550123" },
},
acp: { label: "codex-imessage" },
},
],
}
```
راجع [وكلاء ACP](/tools/acp-agents) للاطلاع على سلوك ارتباط ACP المشترك.
## الكتابة + إيصالات القراءة
- **مؤشرات الكتابة**: يتم إرسالها تلقائيًا قبل وأثناء توليد الرد.
- **إيصالات القراءة**: يتحكم فيها `channels.bluebubbles.sendReadReceipts` ‏(الافتراضي: `true`).
- **مؤشرات الكتابة**: يرسل OpenClaw أحداث بدء الكتابة؛ ويقوم BlueBubbles بمسح حالة الكتابة تلقائيًا عند الإرسال أو انتهاء المهلة (الإيقاف اليدوي عبر DELETE غير موثوق).
```json5
{
channels: {
bluebubbles: {
sendReadReceipts: false, // تعطيل إيصالات القراءة
},
},
}
```
## الإجراءات المتقدمة
يدعم BlueBubbles إجراءات الرسائل المتقدمة عند تمكينها في التكوين:
```json5
{
channels: {
bluebubbles: {
actions: {
reactions: true, // tapbacks (الافتراضي: true)
edit: true, // تحرير الرسائل المرسلة (macOS 13+، معطل على macOS 26 Tahoe)
unsend: true, // إلغاء إرسال الرسائل (macOS 13+)
reply: true, // سلاسل الردود حسب GUID الرسالة
sendWithEffect: true, // تأثيرات الرسائل (slam وloud وما إلى ذلك)
renameGroup: true, // إعادة تسمية الدردشات الجماعية
setGroupIcon: true, // تعيين أيقونة/صورة الدردشة الجماعية (غير مستقر على macOS 26 Tahoe)
addParticipant: true, // إضافة مشاركين إلى المجموعات
removeParticipant: true, // إزالة مشاركين من المجموعات
leaveGroup: true, // مغادرة الدردشات الجماعية
sendAttachment: true, // إرسال المرفقات/الوسائط
},
},
},
}
```
الإجراءات المتاحة:
- **react**: إضافة/إزالة تفاعلات tapback ‏(`messageId` و`emoji` و`remove`)
- **edit**: تحرير رسالة مرسلة (`messageId` و`text`)
- **unsend**: إلغاء إرسال رسالة (`messageId`)
- **reply**: الرد على رسالة محددة (`messageId` و`text` و`to`)
- **sendWithEffect**: الإرسال مع تأثير iMessage ‏(`text` و`to` و`effectId`)
- **renameGroup**: إعادة تسمية دردشة جماعية (`chatGuid` و`displayName`)
- **setGroupIcon**: تعيين أيقونة/صورة دردشة جماعية (`chatGuid` و`media`) — غير مستقر على macOS 26 Tahoe ‏(قد تُرجع API نجاحًا لكن الأيقونة لا تتزامن).
- **addParticipant**: إضافة شخص إلى مجموعة (`chatGuid` و`address`)
- **removeParticipant**: إزالة شخص من مجموعة (`chatGuid` و`address`)
- **leaveGroup**: مغادرة دردشة جماعية (`chatGuid`)
- **upload-file**: إرسال وسائط/ملفات (`to` و`buffer` و`filename` و`asVoice`)
- المذكرات الصوتية: اضبط `asVoice: true` مع صوت **MP3** أو **CAF** للإرسال كرسالة صوتية في iMessage. يقوم BlueBubbles بتحويل MP3 → CAF عند إرسال المذكرات الصوتية.
- الاسم المستعار القديم: ما زال `sendAttachment` يعمل، لكن `upload-file` هو اسم الإجراء المعتمد.
### معرفات الرسائل (القصيرة مقابل الكاملة)
قد يعرض OpenClaw معرفات رسائل _قصيرة_ (مثل `1` و`2`) لتوفير الرموز.
- يمكن أن تكون `MessageSid` / `ReplyToId` معرفات قصيرة.
- تحتوي `MessageSidFull` / `ReplyToIdFull` على المعرفات الكاملة للمزوّد.
- المعرفات القصيرة موجودة في الذاكرة؛ وقد تنتهي صلاحيتها عند إعادة التشغيل أو إخلاء ذاكرة التخزين المؤقت.
- تقبل الإجراءات `messageId` القصير أو الكامل، لكن المعرفات القصيرة ستؤدي إلى خطأ إذا لم تعد متاحة.
استخدم المعرفات الكاملة للأتمتة والتخزين الدائمين:
- القوالب: `{{MessageSidFull}}` و`{{ReplyToIdFull}}`
- السياق: `MessageSidFull` / `ReplyToIdFull` في الحمولات الواردة
راجع [التكوين](/gateway/configuration) للاطلاع على متغيرات القوالب.
## تدفق الكتل
تحكم فيما إذا كانت الردود تُرسل كرسالة واحدة أو تُبث على شكل كتل:
```json5
{
channels: {
bluebubbles: {
blockStreaming: true, // تمكين تدفق الكتل (معطل افتراضيًا)
},
},
}
```
## الوسائط + الحدود
- يتم تنزيل المرفقات الواردة وتخزينها في ذاكرة التخزين المؤقت للوسائط.
- حد الوسائط عبر `channels.bluebubbles.mediaMaxMb` للوسائط الواردة والصادرة (الافتراضي: 8 ميجابايت).
- يتم تجزئة النص الصادر وفق `channels.bluebubbles.textChunkLimit` ‏(الافتراضي: 4000 حرف).
## مرجع التكوين
التكوين الكامل: [التكوين](/gateway/configuration)
خيارات المزوّد:
- `channels.bluebubbles.enabled`: تمكين/تعطيل القناة.
- `channels.bluebubbles.serverUrl`: عنوان URL الأساسي لـ BlueBubbles REST API.
- `channels.bluebubbles.password`: كلمة مرور API.
- `channels.bluebubbles.webhookPath`: مسار نقطة نهاية webhook ‏(الافتراضي: `/bluebubbles-webhook`).
- `channels.bluebubbles.dmPolicy`: ‏`pairing | allowlist | open | disabled` ‏(الافتراضي: `pairing`).
- `channels.bluebubbles.allowFrom`: قائمة السماح للرسائل الخاصة (المقابض، والبريد الإلكتروني، وأرقام E.164، و`chat_id:*`، و`chat_guid:*`).
- `channels.bluebubbles.groupPolicy`: ‏`open | allowlist | disabled` ‏(الافتراضي: `allowlist`).
- `channels.bluebubbles.groupAllowFrom`: قائمة السماح لمرسلي المجموعات.
- `channels.bluebubbles.enrichGroupParticipantsFromContacts`: على macOS، إثراء المشاركين غير المسمّين في المجموعة اختياريًا من Contacts المحلية بعد اجتياز الضبط. الافتراضي: `false`.
- `channels.bluebubbles.groups`: تكوين لكل مجموعة (`requireMention` وما إلى ذلك).
- `channels.bluebubbles.sendReadReceipts`: إرسال إيصالات القراءة (الافتراضي: `true`).
- `channels.bluebubbles.blockStreaming`: تمكين تدفق الكتل (الافتراضي: `false`؛ مطلوب للردود المتدفقة).
- `channels.bluebubbles.textChunkLimit`: حجم التجزئة الصادرة بالأحرف (الافتراضي: 4000).
- `channels.bluebubbles.chunkMode`: يؤدي `length` ‏(الافتراضي) إلى التقسيم فقط عند تجاوز `textChunkLimit`؛ بينما يقسم `newline` عند الأسطر الفارغة (حدود الفقرات) قبل التجزئة حسب الطول.
- `channels.bluebubbles.mediaMaxMb`: حد الوسائط الواردة/الصادرة بالميجابايت (الافتراضي: 8).
- `channels.bluebubbles.mediaLocalRoots`: قائمة سماح صريحة بالأدلة المحلية المطلقة المسموح بها لمسارات الوسائط المحلية الصادرة. يتم رفض الإرسال عبر المسارات المحلية افتراضيًا ما لم يتم تكوين هذا الخيار. تجاوز لكل حساب: `channels.bluebubbles.accounts.<accountId>.mediaLocalRoots`.
- `channels.bluebubbles.historyLimit`: الحد الأقصى لرسائل المجموعة للسياق (يعطل عند 0).
- `channels.bluebubbles.dmHistoryLimit`: حد سجل الرسائل الخاصة.
- `channels.bluebubbles.actions`: تمكين/تعطيل إجراءات محددة.
- `channels.bluebubbles.accounts`: تكوين متعدد الحسابات.
الخيارات العامة ذات الصلة:
- `agents.list[].groupChat.mentionPatterns` (أو `messages.groupChat.mentionPatterns`).
- `messages.responsePrefix`.
## الاستهداف / أهداف التسليم
يفضل استخدام `chat_guid` للتوجيه المستقر:
- `chat_guid:iMessage;-;+15555550123` ‏(مفضل للمجموعات)
- `chat_id:123`
- `chat_identifier:...`
- المقابض المباشرة: `+15555550123` و`user@example.com`
- إذا لم يكن للمقبض المباشر دردشة DM موجودة، فسيقوم OpenClaw بإنشاء واحدة عبر `POST /api/v1/chat/new`. وهذا يتطلب تمكين BlueBubbles Private API.
## الأمان
- تتم مصادقة طلبات webhook عبر مقارنة معاملات الاستعلام `guid`/`password` أو الرؤوس مع `channels.bluebubbles.password`.
- حافظ على سرية كلمة مرور API ونقطة نهاية webhook (تعامل معها على أنها بيانات اعتماد).
- لا يوجد تجاوز localhost لمصادقة BlueBubbles webhook. إذا كنت تمرر حركة webhook عبر proxy، فاحتفظ بكلمة مرور BlueBubbles داخل الطلب من الطرف إلى الطرف. لا يستبدل `gateway.trustedProxies` قيمة `channels.bluebubbles.password` هنا. راجع [أمان Gateway](/gateway/security#reverse-proxy-configuration).
- فعّل HTTPS + قواعد الجدار الناري على خادم BlueBubbles إذا كنت ستعرضه خارج شبكتك المحلية.
## استكشاف الأخطاء وإصلاحها
- إذا توقفت أحداث الكتابة/القراءة عن العمل، فتحقق من سجلات BlueBubbles webhook وتأكد من أن مسار gateway يطابق `channels.bluebubbles.webhookPath`.
- تنتهي صلاحية رموز الاقتران بعد ساعة واحدة؛ استخدم `openclaw pairing list bluebubbles` و`openclaw pairing approve bluebubbles <code>`.
- تتطلب التفاعلات BlueBubbles private API ‏(`POST /api/v1/message/react`)؛ تأكد من أن إصدار الخادم يوفّرها.
- يتطلب التحرير/إلغاء الإرسال macOS 13+ وإصدار BlueBubbles Server متوافقًا. في macOS 26 ‏(Tahoe)، يكون التحرير معطلًا حاليًا بسبب تغييرات في private API.
- قد تكون تحديثات أيقونات المجموعات غير مستقرة على macOS 26 ‏(Tahoe): قد تُرجع API نجاحًا لكن الأيقونة الجديدة لا تتزامن.
- يُخفي OpenClaw تلقائيًا الإجراءات المعروفة بأنها معطلة بناءً على إصدار macOS الخاص بخادم BlueBubbles. إذا استمر ظهور التحرير على macOS 26 ‏(Tahoe)، فعطّله يدويًا باستخدام `channels.bluebubbles.actions.edit=false`.
- لمعلومات الحالة/السلامة: `openclaw status --all` أو `openclaw status --deep`.
للاطلاع على مرجع عام لتدفق القنوات، راجع [القنوات](/channels) ودليل [Plugins](/tools/plugin).
## ذو صلة
- [نظرة عامة على القنوات](/channels) — جميع القنوات المدعومة
- [الاقتران](/channels/pairing) — مصادقة الرسائل الخاصة وتدفق الاقتران
- [المجموعات](/channels/groups) — سلوك الدردشة الجماعية وضبط الإشارات
- [توجيه القنوات](/channels/channel-routing) — توجيه الجلسات للرسائل
- [الأمان](/gateway/security) — نموذج الوصول والتقوية

449
docs/ar/channels/broadcast-groups.md Normal file
View File

@ -0,0 +1,449 @@
---
read_when:
- تكوين مجموعات البث
- تصحيح أخطاء الردود متعددة الوكلاء في WhatsApp
status: experimental
summary: بث رسالة WhatsApp إلى عدة وكلاء
title: مجموعات البث
x-i18n:
generated_at: "2026-04-05T12:35:05Z"
model: gpt-5.4
provider: openai
source_hash: 1d117ae65ec3b63c2bd4b3c215d96f32d7eafa0f99a9cd7378e502c15e56ca56
source_path: channels/broadcast-groups.md
workflow: 15
---
# مجموعات البث
**الحالة:** تجريبية
**الإصدار:** أضيفت في 2026.1.9
## نظرة عامة
تتيح مجموعات البث لعدة وكلاء معالجة الرسالة نفسها والرد عليها في الوقت نفسه. يتيح لك ذلك إنشاء فرق وكلاء متخصصة تعمل معًا داخل مجموعة WhatsApp واحدة أو رسالة خاصة — وكل ذلك باستخدام رقم هاتف واحد.
النطاق الحالي: **WhatsApp فقط** (قناة الويب).
تُقيَّم مجموعات البث بعد قوائم السماح الخاصة بالقنوات وقواعد تفعيل المجموعات. في مجموعات WhatsApp، يعني هذا أن عمليات البث تحدث عندما يكون OpenClaw سيرد عادةً (على سبيل المثال: عند الإشارة، حسب إعدادات مجموعتك).
## حالات الاستخدام
### 1. فرق الوكلاء المتخصصة
انشر عدة وكلاء بمسؤوليات محددة ومركزة:
```
Group: "Development Team"
Agents:
- CodeReviewer (reviews code snippets)
- DocumentationBot (generates docs)
- SecurityAuditor (checks for vulnerabilities)
- TestGenerator (suggests test cases)
```
يعالج كل وكيل الرسالة نفسها ويقدم منظوره المتخصص.
### 2. دعم متعدد اللغات
```
Group: "International Support"
Agents:
- Agent_EN (responds in English)
- Agent_DE (responds in German)
- Agent_ES (responds in Spanish)
```
### 3. سير عمل ضمان الجودة
```
Group: "Customer Support"
Agents:
- SupportAgent (provides answer)
- QAAgent (reviews quality, only responds if issues found)
```
### 4. أتمتة المهام
```
Group: "Project Management"
Agents:
- TaskTracker (updates task database)
- TimeLogger (logs time spent)
- ReportGenerator (creates summaries)
```
## التكوين
### الإعداد الأساسي
أضف قسم `broadcast` على المستوى الأعلى (بجانب `bindings`). المفاتيح هي معرّفات نظير WhatsApp:
- محادثات المجموعات: group JID (مثل `120363403215116621@g.us`)
- الرسائل الخاصة: رقم هاتف بتنسيق E.164 (مثل `+15551234567`)
```json
{
"broadcast": {
"120363403215116621@g.us": ["alfred", "baerbel", "assistant3"]
}
}
```
**النتيجة:** عندما يكون OpenClaw سيرد في هذه الدردشة، سيشغّل الوكلاء الثلاثة جميعهم.
### استراتيجية المعالجة
تحكم في كيفية معالجة الوكلاء للرسائل:
#### بالتوازي (الافتراضي)
يعالج جميع الوكلاء الرسائل في الوقت نفسه:
```json
{
"broadcast": {
"strategy": "parallel",
"120363403215116621@g.us": ["alfred", "baerbel"]
}
}
```
#### بالتسلسل
يعالج الوكلاء الرسائل بالترتيب (ينتظر أحدهم انتهاء السابق):
```json
{
"broadcast": {
"strategy": "sequential",
"120363403215116621@g.us": ["alfred", "baerbel"]
}
}
```
### مثال كامل
```json
{
"agents": {
"list": [
{
"id": "code-reviewer",
"name": "Code Reviewer",
"workspace": "/path/to/code-reviewer",
"sandbox": { "mode": "all" }
},
{
"id": "security-auditor",
"name": "Security Auditor",
"workspace": "/path/to/security-auditor",
"sandbox": { "mode": "all" }
},
{
"id": "docs-generator",
"name": "Documentation Generator",
"workspace": "/path/to/docs-generator",
"sandbox": { "mode": "all" }
}
]
},
"broadcast": {
"strategy": "parallel",
"120363403215116621@g.us": ["code-reviewer", "security-auditor", "docs-generator"],
"120363424282127706@g.us": ["support-en", "support-de"],
"+15555550123": ["assistant", "logger"]
}
}
```
## كيف يعمل
### تدفق الرسائل
1. **تصل رسالة واردة** في مجموعة WhatsApp
2. **فحص البث**: يتحقق النظام مما إذا كان معرّف النظير موجودًا في `broadcast`
3. **إذا كان في قائمة البث**:
- يعالج جميع الوكلاء المدرجين الرسالة
- لكل وكيل مفتاح جلسة خاص به وسياق معزول
- يعالج الوكلاء الرسائل بالتوازي (افتراضيًا) أو بالتسلسل
4. **إذا لم يكن في قائمة البث**:
- يُطبَّق التوجيه العادي (أول binding مطابق)
ملاحظة: لا تتجاوز مجموعات البث قوائم السماح الخاصة بالقنوات أو قواعد تفعيل المجموعات (الإشارات/الأوامر/إلخ). فهي تغيّر فقط _أي الوكلاء يعملون_ عندما تكون الرسالة مؤهلة للمعالجة.
### عزل الجلسات
يحافظ كل وكيل في مجموعة بث على فصل كامل لما يلي:
- **مفاتيح الجلسات** (`agent:alfred:whatsapp:group:120363...` مقابل `agent:baerbel:whatsapp:group:120363...`)
- **سجل المحادثة** (الوكيل لا يرى رسائل الوكلاء الآخرين)
- **مساحة العمل** (بيئات معزولة منفصلة إذا تم تكوينها)
- **الوصول إلى الأدوات** (قوائم سماح/منع مختلفة)
- **الذاكرة/السياق** (`IDENTITY.md` و`SOUL.md` وما إلى ذلك بشكل منفصل)
- **مخزن سياق المجموعة** (رسائل المجموعة الحديثة المستخدمة للسياق) يكون مشتركًا لكل نظير، لذا يرى جميع وكلاء البث السياق نفسه عند التشغيل
وهذا يتيح لكل وكيل أن يمتلك:
- شخصيات مختلفة
- وصولًا مختلفًا إلى الأدوات (مثل للقراءة فقط مقابل القراءة والكتابة)
- نماذج مختلفة (مثل opus مقابل sonnet)
- Skills مختلفة مثبّتة
### مثال: جلسات معزولة
في المجموعة `120363403215116621@g.us` مع الوكلاء `["alfred", "baerbel"]`:
**سياق Alfred:**
```
Session: agent:alfred:whatsapp:group:120363403215116621@g.us
History: [user message, alfred's previous responses]
Workspace: /Users/user/openclaw-alfred/
Tools: read, write, exec
```
**سياق Bärbel:**
```
Session: agent:baerbel:whatsapp:group:120363403215116621@g.us
History: [user message, baerbel's previous responses]
Workspace: /Users/user/openclaw-baerbel/
Tools: read only
```
## أفضل الممارسات
### 1. أبقِ الوكلاء مركّزين
صمّم كل وكيل بحيث تكون له مسؤولية واحدة وواضحة:
```json
{
"broadcast": {
"DEV_GROUP": ["formatter", "linter", "tester"]
}
}
```
✅ **جيد:** لكل وكيل مهمة واحدة
❌ **سيئ:** وكيل عام واحد باسم "dev-helper"
### 2. استخدم أسماء وصفية
اجعل وظيفة كل وكيل واضحة:
```json
{
"agents": {
"security-scanner": { "name": "Security Scanner" },
"code-formatter": { "name": "Code Formatter" },
"test-generator": { "name": "Test Generator" }
}
}
```
### 3. كوّن وصولًا مختلفًا إلى الأدوات
امنح الوكلاء الأدوات التي يحتاجونها فقط:
```json
{
"agents": {
"reviewer": {
"tools": { "allow": ["read", "exec"] } // Read-only
},
"fixer": {
"tools": { "allow": ["read", "write", "edit", "exec"] } // Read-write
}
}
}
```
### 4. راقب الأداء
مع وجود عدد كبير من الوكلاء، ضع في اعتبارك ما يلي:
- استخدام `"strategy": "parallel"` (الافتراضي) للسرعة
- حصر مجموعات البث في 5-10 وكلاء
- استخدام نماذج أسرع للوكلاء الأبسط
### 5. تعامل مع الإخفاقات بسلاسة
يفشل الوكلاء بشكل مستقل. لا يمنع خطأ أحد الوكلاء الآخرين:
```
Message → [Agent A ✓, Agent B ✗ error, Agent C ✓]
Result: Agent A and C respond, Agent B logs error
```
## التوافق
### المزوّدون
تعمل مجموعات البث حاليًا مع:
- ✅ WhatsApp (منفذ)
- 🚧 Telegram (مخطط له)
- 🚧 Discord (مخطط له)
- 🚧 Slack (مخطط له)
### التوجيه
تعمل مجموعات البث إلى جانب التوجيه الحالي:
```json
{
"bindings": [
{
"match": { "channel": "whatsapp", "peer": { "kind": "group", "id": "GROUP_A" } },
"agentId": "alfred"
}
],
"broadcast": {
"GROUP_B": ["agent1", "agent2"]
}
}
```
- `GROUP_A`: يرد alfred فقط (توجيه عادي)
- `GROUP_B`: يرد agent1 وagent2 معًا (بث)
**الأسبقية:** يأخذ `broadcast` الأولوية على `bindings`.
## استكشاف الأخطاء وإصلاحها
### الوكلاء لا يردون
**تحقق من:**
1. وجود معرّفات الوكلاء في `agents.list`
2. صحة تنسيق معرّف النظير (مثل `120363403215116621@g.us`)
3. عدم وجود الوكلاء في قوائم المنع
**التصحيح:**
```bash
tail -f ~/.openclaw/logs/gateway.log | grep broadcast
```
### وكيل واحد فقط يرد
**السبب:** قد يكون معرّف النظير موجودًا في `bindings` ولكن ليس في `broadcast`.
**الحل:** أضفه إلى تكوين البث أو أزله من bindings.
### مشكلات الأداء
**إذا كان الأداء بطيئًا مع عدد كبير من الوكلاء:**
- قلّل عدد الوكلاء لكل مجموعة
- استخدم نماذج أخف (sonnet بدلًا من opus)
- تحقق من وقت بدء تشغيل sandbox
## أمثلة
### المثال 1: فريق مراجعة الشيفرة
```json
{
"broadcast": {
"strategy": "parallel",
"120363403215116621@g.us": [
"code-formatter",
"security-scanner",
"test-coverage",
"docs-checker"
]
},
"agents": {
"list": [
{
"id": "code-formatter",
"workspace": "~/agents/formatter",
"tools": { "allow": ["read", "write"] }
},
{
"id": "security-scanner",
"workspace": "~/agents/security",
"tools": { "allow": ["read", "exec"] }
},
{
"id": "test-coverage",
"workspace": "~/agents/testing",
"tools": { "allow": ["read", "exec"] }
},
{ "id": "docs-checker", "workspace": "~/agents/docs", "tools": { "allow": ["read"] } }
]
}
}
```
**يرسل المستخدم:** مقتطف شيفرة
**الردود:**
- code-formatter: "Fixed indentation and added type hints"
- security-scanner: "⚠️ SQL injection vulnerability in line 12"
- test-coverage: "Coverage is 45%, missing tests for error cases"
- docs-checker: "Missing docstring for function `process_data`"
### المثال 2: دعم متعدد اللغات
```json
{
"broadcast": {
"strategy": "sequential",
"+15555550123": ["detect-language", "translator-en", "translator-de"]
},
"agents": {
"list": [
{ "id": "detect-language", "workspace": "~/agents/lang-detect" },
{ "id": "translator-en", "workspace": "~/agents/translate-en" },
{ "id": "translator-de", "workspace": "~/agents/translate-de" }
]
}
}
```
## مرجع API
### مخطط التكوين
```typescript
interface OpenClawConfig {
broadcast?: {
strategy?: "parallel" | "sequential";
[peerId: string]: string[];
};
}
```
### الحقول
- `strategy` (اختياري): كيفية معالجة الوكلاء
- `"parallel"` (افتراضي): يعالج جميع الوكلاء في الوقت نفسه
- `"sequential"`: يعالج الوكلاء وفق ترتيبهم في المصفوفة
- `[peerId]`: group JID لـ WhatsApp، أو رقم E.164، أو معرّف نظير آخر
- القيمة: مصفوفة من معرّفات الوكلاء الذين يجب أن يعالجوا الرسائل
## القيود
1. **الحد الأقصى للوكلاء:** لا يوجد حد صارم، لكن 10+ وكلاء قد يكونون بطيئين
2. **السياق المشترك:** لا يرى الوكلاء ردود بعضهم البعض (عن قصد)
3. **ترتيب الرسائل:** قد تصل الردود المتوازية بأي ترتيب
4. **حدود المعدل:** تُحتسب جميع الوكلاء ضمن حدود معدل WhatsApp
## تحسينات مستقبلية
الميزات المخطط لها:
- [ ] وضع السياق المشترك (يرى الوكلاء ردود بعضهم البعض)
- [ ] تنسيق الوكلاء (يمكن للوكلاء إرسال إشارات إلى بعضهم البعض)
- [ ] اختيار ديناميكي للوكلاء (اختيار الوكلاء بناءً على محتوى الرسالة)
- [ ] أولويات الوكلاء (يرد بعض الوكلاء قبل الآخرين)
## راجع أيضًا
- [تكوين متعدد الوكلاء](/tools/multi-agent-sandbox-tools)
- [تكوين التوجيه](/channels/channel-routing)
- [إدارة الجلسات](/concepts/session)

146
docs/ar/channels/channel-routing.md Normal file
View File

@ -0,0 +1,146 @@
---
read_when:
- تغيير توجيه القنوات أو سلوك صندوق الوارد
summary: قواعد التوجيه لكل قناة (WhatsApp وTelegram وDiscord وSlack) والسياق المشترك
title: توجيه القنوات
x-i18n:
generated_at: "2026-04-05T12:34:40Z"
model: gpt-5.4
provider: openai
source_hash: 63916c4dd0af5fc9bbd12581a9eb15fea14a380c5ade09323ca0c237db61e537
source_path: channels/channel-routing.md
workflow: 15
---
# القنوات والتوجيه
يوجّه OpenClaw الردود **مرة أخرى إلى القناة التي جاءت منها الرسالة**. لا
يختار النموذج قناة؛ فالتوجيه حتمي وتتحكم فيه
إعدادات المضيف.
## المصطلحات الأساسية
- **القناة**: `telegram` و`whatsapp` و`discord` و`irc` و`googlechat` و`slack` و`signal` و`imessage` و`line`، بالإضافة إلى قنوات الإضافات. `webchat` هي قناة واجهة WebChat الداخلية وليست قناة صادرة قابلة للإعداد.
- **AccountId**: مثيل حساب لكل قناة (عند الدعم).
- الحساب الافتراضي الاختياري للقناة: يحدد `channels.<channel>.defaultAccount`
الحساب المستخدم عندما لا يحدد مسار صادر قيمة `accountId`.
- في إعدادات الحسابات المتعددة، عيّن قيمة افتراضية صريحة (`defaultAccount` أو `accounts.default`) عند إعداد حسابين أو أكثر. وبدون ذلك، قد يختار التوجيه الاحتياطي أول معرّف حساب مُطبّع.
- **AgentId**: مساحة عمل + مخزن جلسات معزولان ("العقل").
- **SessionKey**: مفتاح الحاوية المستخدم لتخزين السياق والتحكم في التزامن.
## أشكال مفاتيح الجلسات (أمثلة)
تُطوى الرسائل المباشرة إلى جلسة **الرئيسية** الخاصة بالوكيل:
- `agent:<agentId>:<mainKey>` (الافتراضي: `agent:main:main`)
وتبقى المجموعات والقنوات معزولة لكل قناة:
- المجموعات: `agent:<agentId>:<channel>:group:<id>`
- القنوات/الغرف: `agent:<agentId>:<channel>:channel:<id>`
سلاسل الرسائل:
- تضيف سلاسل Slack/Discord القيمة `:thread:<threadId>` إلى المفتاح الأساسي.
- تدمج موضوعات منتدى Telegram القيمة `:topic:<topicId>` في مفتاح المجموعة.
أمثلة:
- `agent:main:telegram:group:-1001234567890:topic:42`
- `agent:main:discord:channel:123456:thread:987654`
## تثبيت مسار الرسائل المباشرة الرئيسية
عندما تكون قيمة `session.dmScope` هي `main`، قد تشترك الرسائل المباشرة في جلسة رئيسية واحدة.
ولمنع الكتابة فوق `lastRoute` الخاص بالجلسة بواسطة الرسائل المباشرة من غير المالك،
يستنتج OpenClaw مالكًا مثبتًا من `allowFrom` عندما تتحقق جميع الشروط التالية:
- يحتوي `allowFrom` على إدخال واحد غير شامل تمامًا.
- يمكن تطبيع هذا الإدخال إلى معرّف مرسل فعلي لتلك القناة.
- لا يتطابق مرسل الرسالة المباشرة الواردة مع ذلك المالك المثبت.
في حالة عدم التطابق هذه، يواصل OpenClaw تسجيل بيانات تعريف الجلسة الواردة، لكنه
يتخطى تحديث `lastRoute` للجلسة الرئيسية.
## قواعد التوجيه (كيف يتم اختيار الوكيل)
يختار التوجيه **وكيلًا واحدًا** لكل رسالة واردة:
1. **مطابقة نظير تامة** (`bindings` مع `peer.kind` و`peer.id`).
2. **مطابقة النظير الأصل** (وراثة السلسلة).
3. **مطابقة الخادم + الأدوار** (Discord) عبر `guildId` و`roles`.
4. **مطابقة الخادم** (Discord) عبر `guildId`.
5. **مطابقة الفريق** (Slack) عبر `teamId`.
6. **مطابقة الحساب** (`accountId` على القناة).
7. **مطابقة القناة** (أي حساب على تلك القناة، `accountId: "*"`).
8. **الوكيل الافتراضي** (`agents.list[].default`، وإلا أول إدخال في القائمة، مع الرجوع الاحتياطي إلى `main`).
عندما يتضمن الربط عدة حقول مطابقة (`peer` أو `guildId` أو `teamId` أو `roles`)، **يجب أن تتطابق جميع الحقول المقدمة** حتى يُطبَّق هذا الربط.
يحدد الوكيل المطابق مساحة العمل ومخزن الجلسات المستخدمين.
## مجموعات البث (تشغيل عدة وكلاء)
تتيح لك مجموعات البث تشغيل **عدة وكلاء** للنظير نفسه **عندما يكون OpenClaw سيرد عادةً** (على سبيل المثال: في مجموعات WhatsApp، بعد ذكر الاسم/بوابة التفعيل).
الإعداد:
```json5
{
broadcast: {
strategy: "parallel",
"120363403215116621@g.us": ["alfred", "baerbel"],
"+15555550123": ["support", "logger"],
},
}
```
راجع: [مجموعات البث](/channels/broadcast-groups).
## نظرة عامة على الإعداد
- `agents.list`: تعريفات الوكلاء المسماة (مساحة العمل، النموذج، وما إلى ذلك).
- `bindings`: ربط القنوات/الحسابات/النظراء الواردة بالوكلاء.
مثال:
```json5
{
agents: {
list: [{ id: "support", name: "Support", workspace: "~/.openclaw/workspace-support" }],
},
bindings: [
{ match: { channel: "slack", teamId: "T123" }, agentId: "support" },
{ match: { channel: "telegram", peer: { kind: "group", id: "-100123" } }, agentId: "support" },
],
}
```
## تخزين الجلسات
توجد مخازن الجلسات ضمن دليل الحالة (الافتراضي `~/.openclaw`):
- `~/.openclaw/agents/<agentId>/sessions/sessions.json`
- توجد نصوص JSONL بجانب المخزن
يمكنك تجاوز مسار المخزن عبر `session.store` وقوالب `{agentId}`.
يفحص اكتشاف جلسات Gateway وACP أيضًا مخازن الوكلاء المعتمدة على القرص ضمن
الجذر الافتراضي `agents/` وضمن جذور `session.store` ذات القوالب. ويجب أن تبقى
المخازن المكتشفة داخل جذر الوكيل المحلول هذا وأن تستخدم ملف
`sessions.json` عاديًا. يتم تجاهل الروابط الرمزية والمسارات الخارجة عن الجذر.
## سلوك WebChat
يرتبط WebChat بـ **الوكيل المحدد** ويستخدم افتراضيًا الجلسة الرئيسية للوكيل.
ولهذا السبب، يتيح لك WebChat رؤية السياق المشترك بين القنوات لذلك
الوكيل في مكان واحد.
## سياق الرد
تتضمن الردود الواردة ما يلي:
- `ReplyToId` و`ReplyToBody` و`ReplyToSender` عند توفرها.
- يُلحَق السياق المقتبس بـ `Body` ككتلة `[Replying to ...]`.
وهذا متسق عبر القنوات.

1261
docs/ar/channels/discord.md Normal file
View File

File diff suppressed because it is too large Load Diff

796
docs/ar/channels/feishu.md Normal file
View File

@ -0,0 +1,796 @@
---
read_when:
- تريد توصيل بوت Feishu/Lark
- أنت تقوم بإعداد قناة Feishu
summary: نظرة عامة على بوت Feishu وميزاته وإعداده
title: Feishu
x-i18n:
generated_at: "2026-04-05T12:35:34Z"
model: gpt-5.4
provider: openai
source_hash: 4e39b6dfe3a3aa4ebbdb992975e570e4f1b5e79f3b400a555fc373a0d1889952
source_path: channels/feishu.md
workflow: 15
---
# بوت Feishu
Feishu ‏(Lark) هو نظام دردشة جماعي تستخدمه الشركات للمراسلة والتعاون. يربط هذا الـ plugin بين OpenClaw وبوت Feishu/Lark باستخدام اشتراك أحداث WebSocket الخاص بالمنصة، بحيث يمكن استقبال الرسائل من دون تعريض عنوان URL عام لـ webhook.
---
## الـ plugin المضمّن
يأتي Feishu مضمّنًا مع إصدارات OpenClaw الحالية، لذلك لا يلزم تثبيت plugin منفصل.
إذا كنت تستخدم إصدارًا أقدم أو تثبيتًا مخصصًا لا يتضمن Feishu المضمّن، فقم بتثبيته يدويًا:
```bash
openclaw plugins install @openclaw/feishu
```
---
## البدء السريع
هناك طريقتان لإضافة قناة Feishu:
### الطريقة 1: الإعداد الأولي (مستحسن)
إذا كنت قد ثبّت OpenClaw للتو، فشغّل الإعداد الأولي:
```bash
openclaw onboard
```
سيرشدك المعالج خلال ما يلي:
1. إنشاء تطبيق Feishu وجمع بيانات الاعتماد
2. إعداد بيانات اعتماد التطبيق في OpenClaw
3. بدء تشغيل البوابة
✅ **بعد الإعداد**، تحقّق من حالة البوابة:
- `openclaw gateway status`
- `openclaw logs --follow`
### الطريقة 2: الإعداد عبر CLI
إذا كنت قد أكملت التثبيت الأولي بالفعل، فأضف القناة عبر CLI:
```bash
openclaw channels add
```
اختر **Feishu**، ثم أدخل App ID وApp Secret.
✅ **بعد الإعداد**، أدر البوابة:
- `openclaw gateway status`
- `openclaw gateway restart`
- `openclaw logs --follow`
---
## الخطوة 1: إنشاء تطبيق Feishu
### 1. افتح Feishu Open Platform
زر [Feishu Open Platform](https://open.feishu.cn/app) وسجّل الدخول.
يجب على مستأجري Lark (العالمي) استخدام [https://open.larksuite.com/app](https://open.larksuite.com/app) وضبط `domain: "lark"` في إعدادات Feishu.
### 2. أنشئ تطبيقًا
1. انقر **Create enterprise app**
2. املأ اسم التطبيق والوصف
3. اختر أيقونة للتطبيق
![Create enterprise app](/images/feishu-step2-create-app.png)
### 3. انسخ بيانات الاعتماد
من **Credentials & Basic Info**، انسخ:
- **App ID** (بالتنسيق: `cli_xxx`)
- **App Secret**
❗ **مهم:** احتفظ بـ App Secret بشكل خاص.
![Get credentials](/images/feishu-step3-credentials.png)
### 4. إعداد الأذونات
في **Permissions**، انقر **Batch import** والصق:
```json
{
"scopes": {
"tenant": [
"aily:file:read",
"aily:file:write",
"application:application.app_message_stats.overview:readonly",
"application:application:self_manage",
"application:bot.menu:write",
"cardkit:card:read",
"cardkit:card:write",
"contact:user.employee_id:readonly",
"corehr:file:download",
"event:ip_list",
"im:chat.access_event.bot_p2p_chat:read",
"im:chat.members:bot_access",
"im:message",
"im:message.group_at_msg:readonly",
"im:message.p2p_msg:readonly",
"im:message:readonly",
"im:message:send_as_bot",
"im:resource"
],
"user": ["aily:file:read", "aily:file:write", "im:chat.access_event.bot_p2p_chat:read"]
}
}
```
![Configure permissions](/images/feishu-step4-permissions.png)
### 5. فعّل إمكانية البوت
في **App Capability** > **Bot**:
1. فعّل إمكانية البوت
2. عيّن اسم البوت
![Enable bot capability](/images/feishu-step5-bot-capability.png)
### 6. إعداد اشتراك الأحداث
⚠️ **مهم:** قبل إعداد اشتراك الأحداث، تأكد من:
1. أنك شغّلت بالفعل `openclaw channels add` لـ Feishu
2. أن البوابة قيد التشغيل (`openclaw gateway status`)
في **Event Subscription**:
1. اختر **Use long connection to receive events** ‏(WebSocket)
2. أضف الحدث: `im.message.receive_v1`
3. (اختياري) لمهام تعليقات Drive، أضف أيضًا: `drive.notice.comment_add_v1`
⚠️ إذا لم تكن البوابة قيد التشغيل، فقد يفشل حفظ إعداد الاتصال الطويل.
![Configure event subscription](/images/feishu-step6-event-subscription.png)
### 7. انشر التطبيق
1. أنشئ إصدارًا في **Version Management & Release**
2. أرسله للمراجعة وانشره
3. انتظر موافقة المسؤول (تطبيقات المؤسسات تُوافق عادةً تلقائيًا)
---
## الخطوة 2: إعداد OpenClaw
### الإعداد باستخدام المعالج (مستحسن)
```bash
openclaw channels add
```
اختر **Feishu** والصق App ID وApp Secret.
### الإعداد عبر ملف التهيئة
حرّر `~/.openclaw/openclaw.json`:
```json5
{
channels: {
feishu: {
enabled: true,
dmPolicy: "pairing",
accounts: {
main: {
appId: "cli_xxx",
appSecret: "xxx",
name: "My AI assistant",
},
},
},
},
}
```
إذا كنت تستخدم `connectionMode: "webhook"`، فاضبط كلًا من `verificationToken` و`encryptKey`. يرتبط خادم webhook الخاص بـ Feishu على `127.0.0.1` افتراضيًا؛ لا تضبط `webhookHost` إلا إذا كنت تحتاج عمدًا إلى عنوان ربط مختلف.
#### Verification Token وEncrypt Key ‏(وضع webhook)
عند استخدام وضع webhook، اضبط كلًا من `channels.feishu.verificationToken` و`channels.feishu.encryptKey` في إعداداتك. للحصول على القيم:
1. في Feishu Open Platform، افتح تطبيقك
2. انتقل إلى **Development** → **Events & Callbacks** ‏(开发配置 → 事件与回调)
3. افتح تبويب **Encryption** ‏(加密策略)
4. انسخ **Verification Token** و**Encrypt Key**
توضح الصورة التالية مكان العثور على **Verification Token**. أما **Encrypt Key** فهو مدرج في القسم نفسه **Encryption**.
![Verification Token location](/images/feishu-verification-token.png)
### الإعداد عبر متغيرات البيئة
```bash
export FEISHU_APP_ID="cli_xxx"
export FEISHU_APP_SECRET="xxx"
```
### نطاق Lark (العالمي)
إذا كان المستأجر الخاص بك على Lark (الدولي)، فاضبط النطاق إلى `lark` (أو سلسلة نطاق كاملة). يمكنك ضبطه في `channels.feishu.domain` أو لكل حساب على حدة (`channels.feishu.accounts.<id>.domain`).
```json5
{
channels: {
feishu: {
domain: "lark",
accounts: {
main: {
appId: "cli_xxx",
appSecret: "xxx",
},
},
},
},
}
```
### علامات تحسين الحصة
يمكنك تقليل استخدام Feishu API باستخدام علامتين اختياريتين:
- `typingIndicator` (الافتراضي `true`): عند ضبطه على `false`، يتم تخطي استدعاءات تفاعل الكتابة.
- `resolveSenderNames` (الافتراضي `true`): عند ضبطه على `false`، يتم تخطي استدعاءات البحث عن ملف المُرسِل الشخصي.
اضبطهما على المستوى الأعلى أو لكل حساب:
```json5
{
channels: {
feishu: {
typingIndicator: false,
resolveSenderNames: false,
accounts: {
main: {
appId: "cli_xxx",
appSecret: "xxx",
typingIndicator: true,
resolveSenderNames: false,
},
},
},
},
}
```
---
## الخطوة 3: البدء + الاختبار
### 1. شغّل البوابة
```bash
openclaw gateway
```
### 2. أرسل رسالة اختبار
في Feishu، ابحث عن البوت وأرسل رسالة.
### 3. وافق على الاقتران
بشكل افتراضي، يرد البوت برمز اقتران. وافق عليه:
```bash
openclaw pairing approve feishu <CODE>
```
بعد الموافقة، يمكنك الدردشة بشكل طبيعي.
---
## نظرة عامة
- **قناة بوت Feishu**: بوت Feishu تديره البوابة
- **توجيه حتمي**: تعود الردود دائمًا إلى Feishu
- **عزل الجلسات**: تشترك الرسائل الخاصة في جلسة رئيسية؛ أما المجموعات فمعزولة
- **اتصال WebSocket**: اتصال طويل عبر Feishu SDK، ولا حاجة إلى عنوان URL عام
---
## التحكم في الوصول
### الرسائل المباشرة
- **الافتراضي**: `dmPolicy: "pairing"` ‏(يحصل المستخدمون غير المعروفين على رمز اقتران)
- **الموافقة على الاقتران**:
```bash
openclaw pairing list feishu
openclaw pairing approve feishu <CODE>
```
- **وضع قائمة السماح**: اضبط `channels.feishu.allowFrom` باستخدام Open IDs المسموح بها
### دردشات المجموعات
**1. سياسة المجموعات** (`channels.feishu.groupPolicy`):
- `"open"` = السماح للجميع في المجموعات
- `"allowlist"` = السماح فقط لما هو موجود في `groupAllowFrom`
- `"disabled"` = تعطيل رسائل المجموعات
الافتراضي: `allowlist`
**2. شرط الإشارة** (`channels.feishu.requireMention`، ويمكن تجاوزه عبر `channels.feishu.groups.<chat_id>.requireMention`):
- `true` صراحةً = يتطلب @mention
- `false` صراحةً = يرد من دون إشارات
- عند عدم ضبطه ووجود `groupPolicy: "open"` = الافتراضي `false`
- عند عدم ضبطه وكون `groupPolicy` ليس `"open"` = الافتراضي `true`
---
## أمثلة على إعداد المجموعات
### السماح لجميع المجموعات، من دون الحاجة إلى @mention ‏(الافتراضي للمجموعات المفتوحة)
```json5
{
channels: {
feishu: {
groupPolicy: "open",
},
},
}
```
### السماح لجميع المجموعات، مع الاستمرار في طلب @mention
```json5
{
channels: {
feishu: {
groupPolicy: "open",
requireMention: true,
},
},
}
```
### السماح بمجموعات محددة فقط
```json5
{
channels: {
feishu: {
groupPolicy: "allowlist",
// Feishu group IDs (chat_id) look like: oc_xxx
groupAllowFrom: ["oc_xxx", "oc_yyy"],
},
},
}
```
### تقييد المرسلين المسموح لهم بالمراسلة داخل مجموعة (قائمة سماح للمرسلين)
بالإضافة إلى السماح للمجموعة نفسها، فإن **كل الرسائل** داخل تلك المجموعة يتم ضبطها حسب `open_id` الخاص بالمرسل: فقط المستخدمون المدرجون في `groups.<chat_id>.allowFrom` تتم معالجة رسائلهم؛ أما الرسائل من الأعضاء الآخرين فيتم تجاهلها (هذا ضبط كامل على مستوى المرسل، وليس فقط لأوامر التحكم مثل `/reset` أو `/new`).
```json5
{
channels: {
feishu: {
groupPolicy: "allowlist",
groupAllowFrom: ["oc_xxx"],
groups: {
oc_xxx: {
// Feishu user IDs (open_id) look like: ou_xxx
allowFrom: ["ou_user1", "ou_user2"],
},
},
},
},
}
```
---
<a id="get-groupuser-ids"></a>
## الحصول على معرّفات المجموعة/المستخدم
### معرّفات المجموعات (chat_id)
تبدو معرّفات المجموعات بهذا الشكل `oc_xxx`.
**الطريقة 1 (مستحسنة)**
1. شغّل البوابة واذكر البوت باستخدام @mention داخل المجموعة
2. شغّل `openclaw logs --follow` وابحث عن `chat_id`
**الطريقة 2**
استخدم مصحح Feishu API لسرد دردشات المجموعات.
### معرّفات المستخدمين (open_id)
تبدو معرّفات المستخدمين بهذا الشكل `ou_xxx`.
**الطريقة 1 (مستحسنة)**
1. شغّل البوابة وأرسل رسالة مباشرة إلى البوت
2. شغّل `openclaw logs --follow` وابحث عن `open_id`
**الطريقة 2**
تحقق من طلبات الاقتران للحصول على Open IDs الخاصة بالمستخدمين:
```bash
openclaw pairing list feishu
```
---
## الأوامر الشائعة
| الأمر | الوصف |
| --------- | ----------------- |
| `/status` | عرض حالة البوت |
| `/reset` | إعادة تعيين الجلسة |
| `/model` | عرض/تبديل النموذج |
> ملاحظة: لا يدعم Feishu قوائم الأوامر الأصلية حتى الآن، لذلك يجب إرسال الأوامر كنص.
## أوامر إدارة البوابة
| الأمر | الوصف |
| -------------------------- | ----------------------------- |
| `openclaw gateway status` | عرض حالة البوابة |
| `openclaw gateway install` | تثبيت/بدء خدمة البوابة |
| `openclaw gateway stop` | إيقاف خدمة البوابة |
| `openclaw gateway restart` | إعادة تشغيل خدمة البوابة |
| `openclaw logs --follow` | تتبع سجلات البوابة |
---
## استكشاف الأخطاء وإصلاحها
### البوت لا يستجيب في دردشات المجموعات
1. تأكد من إضافة البوت إلى المجموعة
2. تأكد من أنك تشير إلى البوت باستخدام @mention ‏(السلوك الافتراضي)
3. تحقق من أن `groupPolicy` ليس مضبوطًا على `"disabled"`
4. تحقق من السجلات: `openclaw logs --follow`
### البوت لا يستقبل الرسائل
1. تأكد من أن التطبيق منشور ومعتمد
2. تأكد من أن اشتراك الأحداث يتضمن `im.message.receive_v1`
3. تأكد من تفعيل **long connection**
4. تأكد من اكتمال أذونات التطبيق
5. تأكد من أن البوابة قيد التشغيل: `openclaw gateway status`
6. تحقق من السجلات: `openclaw logs --follow`
### تسرّب App Secret
1. أعد تعيين App Secret في Feishu Open Platform
2. حدّث App Secret في إعداداتك
3. أعد تشغيل البوابة
### فشل إرسال الرسائل
1. تأكد من أن التطبيق يملك إذن `im:message:send_as_bot`
2. تأكد من أن التطبيق منشور
3. تحقق من السجلات للحصول على أخطاء مفصلة
---
## الإعداد المتقدم
### حسابات متعددة
```json5
{
channels: {
feishu: {
defaultAccount: "main",
accounts: {
main: {
appId: "cli_xxx",
appSecret: "xxx",
name: "Primary bot",
},
backup: {
appId: "cli_yyy",
appSecret: "yyy",
name: "Backup bot",
enabled: false,
},
},
},
},
}
```
يتحكم `defaultAccount` في حساب Feishu المستخدم عندما لا تحدد واجهات API الصادرة `accountId` بشكل صريح.
### حدود الرسائل
- `textChunkLimit`: حجم مقطع النص الصادر (الافتراضي: 2000 حرف)
- `mediaMaxMb`: حد رفع/تنزيل الوسائط (الافتراضي: 30MB)
### البث
يدعم Feishu الردود المتدفقة عبر البطاقات التفاعلية. عند التفعيل، يحدّث البوت بطاقة أثناء توليد النص.
```json5
{
channels: {
feishu: {
streaming: true, // enable streaming card output (default true)
blockStreaming: true, // enable block-level streaming (default true)
},
},
}
```
اضبط `streaming: false` للانتظار حتى يكتمل الرد بالكامل قبل الإرسال.
### جلسات ACP
يدعم Feishu ‏ACP في:
- الرسائل المباشرة
- محادثات موضوعات المجموعات
يعتمد ACP في Feishu على أوامر نصية. لا توجد قوائم أوامر slash أصلية، لذا استخدم رسائل `/acp ...` مباشرة في المحادثة.
#### ارتباطات ACP الدائمة
استخدم ارتباطات ACP المكتوبة على المستوى الأعلى لتثبيت رسالة مباشرة أو محادثة موضوع في Feishu إلى جلسة ACP دائمة.
```json5
{
agents: {
list: [
{
id: "codex",
runtime: {
type: "acp",
acp: {
agent: "codex",
backend: "acpx",
mode: "persistent",
cwd: "/workspace/openclaw",
},
},
},
],
},
bindings: [
{
type: "acp",
agentId: "codex",
match: {
channel: "feishu",
accountId: "default",
peer: { kind: "direct", id: "ou_1234567890" },
},
},
{
type: "acp",
agentId: "codex",
match: {
channel: "feishu",
accountId: "default",
peer: { kind: "group", id: "oc_group_chat:topic:om_topic_root" },
},
acp: { label: "codex-feishu-topic" },
},
],
}
```
#### إنشاء ACP مرتبط بسلسلة محادثة من الدردشة
في رسالة مباشرة أو محادثة موضوع في Feishu، يمكنك إنشاء جلسة ACP وربطها في مكانها:
```text
/acp spawn codex --thread here
```
ملاحظات:
- يعمل `--thread here` مع الرسائل المباشرة وموضوعات Feishu.
- يتم توجيه الرسائل اللاحقة في الرسالة المباشرة/الموضوع المرتبط مباشرة إلى جلسة ACP تلك.
- لا يستهدف الإصدار v1 دردشات المجموعات العامة غير المرتبطة بموضوع.
### توجيه متعدد الوكلاء
استخدم `bindings` لتوجيه الرسائل المباشرة أو المجموعات في Feishu إلى وكلاء مختلفين.
```json5
{
agents: {
list: [
{ id: "main" },
{
id: "clawd-fan",
workspace: "/home/user/clawd-fan",
agentDir: "/home/user/.openclaw/agents/clawd-fan/agent",
},
{
id: "clawd-xi",
workspace: "/home/user/clawd-xi",
agentDir: "/home/user/.openclaw/agents/clawd-xi/agent",
},
],
},
bindings: [
{
agentId: "main",
match: {
channel: "feishu",
peer: { kind: "direct", id: "ou_xxx" },
},
},
{
agentId: "clawd-fan",
match: {
channel: "feishu",
peer: { kind: "direct", id: "ou_yyy" },
},
},
{
agentId: "clawd-xi",
match: {
channel: "feishu",
peer: { kind: "group", id: "oc_zzz" },
},
},
],
}
```
حقول التوجيه:
- `match.channel`: ‏`"feishu"`
- `match.peer.kind`: ‏`"direct"` أو `"group"`
- `match.peer.id`: معرّف Open للمستخدم (`ou_xxx`) أو معرّف المجموعة (`oc_xxx`)
راجع [الحصول على معرّفات المجموعة/المستخدم](#get-groupuser-ids) للحصول على نصائح البحث.
---
## مرجع الإعداد
الإعداد الكامل: [إعدادات البوابة](/gateway/configuration)
الخيارات الأساسية:
| الإعداد | الوصف | الافتراضي |
| ------------------------------------------------- | --------------------------------------- | ---------------- |
| `channels.feishu.enabled` | تفعيل/تعطيل القناة | `true` |
| `channels.feishu.domain` | نطاق API ‏(`feishu` أو `lark`) | `feishu` |
| `channels.feishu.connectionMode` | وضع نقل الأحداث | `websocket` |
| `channels.feishu.defaultAccount` | معرّف الحساب الافتراضي للتوجيه الصادر | `default` |
| `channels.feishu.verificationToken` | مطلوب لوضع webhook | - |
| `channels.feishu.encryptKey` | مطلوب لوضع webhook | - |
| `channels.feishu.webhookPath` | مسار route لـ webhook | `/feishu/events` |
| `channels.feishu.webhookHost` | مضيف الربط لـ webhook | `127.0.0.1` |
| `channels.feishu.webhookPort` | منفذ الربط لـ webhook | `3000` |
| `channels.feishu.accounts.<id>.appId` | App ID | - |
| `channels.feishu.accounts.<id>.appSecret` | App Secret | - |
| `channels.feishu.accounts.<id>.domain` | تجاوز نطاق API لكل حساب | `feishu` |
| `channels.feishu.dmPolicy` | سياسة الرسائل المباشرة | `pairing` |
| `channels.feishu.allowFrom` | قائمة السماح للرسائل المباشرة (قائمة `open_id`) | - |
| `channels.feishu.groupPolicy` | سياسة المجموعات | `allowlist` |
| `channels.feishu.groupAllowFrom` | قائمة السماح للمجموعات | - |
| `channels.feishu.requireMention` | طلب @mention افتراضيًا | مشروط |
| `channels.feishu.groups.<chat_id>.requireMention` | تجاوز طلب @mention لكل مجموعة | موروث |
| `channels.feishu.groups.<chat_id>.enabled` | تفعيل المجموعة | `true` |
| `channels.feishu.textChunkLimit` | حجم مقطع الرسالة | `2000` |
| `channels.feishu.mediaMaxMb` | حد حجم الوسائط | `30` |
| `channels.feishu.streaming` | تفعيل خرج البطاقات المتدفقة | `true` |
| `channels.feishu.blockStreaming` | تفعيل البث على مستوى الكتل | `true` |
---
## مرجع dmPolicy
| القيمة | السلوك |
| ------------- | --------------------------------------------------------------- |
| `"pairing"` | **الافتراضي.** يحصل المستخدمون غير المعروفين على رمز اقتران؛ ويجب اعتمادهم |
| `"allowlist"` | فقط المستخدمون الموجودون في `allowFrom` يمكنهم الدردشة |
| `"open"` | السماح لجميع المستخدمين (يتطلب `"*"` في `allowFrom`) |
| `"disabled"` | تعطيل الرسائل المباشرة |
---
## أنواع الرسائل المدعومة
### الاستقبال
- ✅ نص
- ✅ نص منسق (post)
- ✅ صور
- ✅ ملفات
- ✅ صوت
- ✅ فيديو/وسائط
- ✅ ملصقات
### الإرسال
- ✅ نص
- ✅ صور
- ✅ ملفات
- ✅ صوت
- ✅ فيديو/وسائط
- ✅ بطاقات تفاعلية
- ⚠️ نص منسق (تنسيق بنمط post وبطاقات، وليس ميزات التأليف العشوائية في Feishu)
### سلاسل المحادثات والردود
- ✅ ردود مضمّنة
- ✅ ردود سلسلة الموضوع عندما يوفّر Feishu ‏`reply_in_thread`
- ✅ تظل ردود الوسائط مدركة للسلسلة عند الرد على رسالة سلسلة/موضوع
## تعليقات Drive
يمكن لـ Feishu تشغيل الوكيل عندما يضيف شخص ما تعليقًا على مستند Feishu Drive ‏(Docs وSheets وغيرها). يتلقى الوكيل نص التعليق وسياق المستند وسلسلة التعليق حتى يتمكن من الرد داخل السلسلة أو إجراء تعديلات على المستند.
المتطلبات:
- الاشتراك في `drive.notice.comment_add_v1` ضمن إعدادات اشتراك أحداث تطبيق Feishu
(إلى جانب `im.message.receive_v1` الموجود)
- أداة Drive مفعلة افتراضيًا؛ عطّلها باستخدام `channels.feishu.tools.drive: false`
تكشف أداة `feishu_drive` عن إجراءات التعليقات التالية:
| الإجراء | الوصف |
| ---------------------- | ----------------------------------- |
| `list_comments` | سرد التعليقات على مستند |
| `list_comment_replies` | سرد الردود في سلسلة تعليق |
| `add_comment` | إضافة تعليق جديد على المستوى الأعلى |
| `reply_comment` | الرد على سلسلة تعليق موجودة |
عندما يتعامل الوكيل مع حدث تعليق Drive، فإنه يتلقى:
- نص التعليق والمرسل
- بيانات المستند الوصفية (العنوان والنوع وURL)
- سياق سلسلة التعليق للردود داخل السلسلة
بعد إجراء تعديلات على المستند، يتم توجيه الوكيل لاستخدام `feishu_drive.reply_comment` لإخطار
المعلّق ثم إخراج الرمز الصامت المطابق تمامًا `NO_REPLY` / `no_reply` لتجنب
الإرسال المكرر.
## سطح إجراءات وقت التشغيل
يكشف Feishu حاليًا عن إجراءات وقت التشغيل التالية:
- `send`
- `read`
- `edit`
- `thread-reply`
- `pin`
- `list-pins`
- `unpin`
- `member-info`
- `channel-info`
- `channel-list`
- `react` و`reactions` عندما تكون التفاعلات مفعّلة في الإعدادات
- إجراءات تعليقات `feishu_drive`: ‏`list_comments` و`list_comment_replies` و`add_comment` و`reply_comment`
## ذو صلة
- [نظرة عامة على القنوات](/channels) — جميع القنوات المدعومة
- [الاقتران](/channels/pairing) — مصادقة الرسائل المباشرة وتدفق الاقتران
- [المجموعات](/channels/groups) — سلوك دردشات المجموعات وضبط الإشارات
- [توجيه القنوات](/channels/channel-routing) — توجيه الجلسات للرسائل
- [الأمان](/gateway/security) — نموذج الوصول والتحصين

277
docs/ar/channels/googlechat.md Normal file
View File

@ -0,0 +1,277 @@
---
read_when:
- العمل على ميزات قناة Google Chat
summary: حالة دعم تطبيق Google Chat وإمكاناته وتكوينه
title: Google Chat
x-i18n:
generated_at: "2026-04-05T12:35:08Z"
model: gpt-5.4
provider: openai
source_hash: 570894ed798dd0b9ba42806b050927216379a1228fcd2f96de565bc8a4ac7c2c
source_path: channels/googlechat.md
workflow: 15
---
# Google Chat (Chat API)
الحالة: جاهز للرسائل المباشرة + المساحات عبر webhooks الخاصة بـ Google Chat API (HTTP فقط).
## إعداد سريع (للمبتدئين)
1. أنشئ مشروع Google Cloud وفعّل **Google Chat API**.
- انتقل إلى: [Google Chat API Credentials](https://console.cloud.google.com/apis/api/chat.googleapis.com/credentials)
- فعّل API إذا لم تكن مفعلة بالفعل.
2. أنشئ **Service Account**:
- اضغط **Create Credentials** > **Service Account**.
- سمّه كما تريد (مثلًا: `openclaw-chat`).
- اترك الأذونات فارغة (اضغط **Continue**).
- اترك الجهات الرئيسية التي لديها وصول فارغة (اضغط **Done**).
3. أنشئ ونزّل **JSON Key**:
- في قائمة حسابات الخدمة، انقر على الحساب الذي أنشأته للتو.
- انتقل إلى علامة التبويب **Keys**.
- انقر **Add Key** > **Create new key**.
- اختر **JSON** واضغط **Create**.
4. خزّن ملف JSON الذي تم تنزيله على مضيف gateway لديك (مثلًا: `~/.openclaw/googlechat-service-account.json`).
5. أنشئ تطبيق Google Chat في [Google Cloud Console Chat Configuration](https://console.cloud.google.com/apis/api/chat.googleapis.com/hangouts-chat):
- املأ **Application info**:
- **App name**: (مثلًا `OpenClaw`)
- **Avatar URL**: (مثلًا `https://openclaw.ai/logo.png`)
- **Description**: (مثلًا `Personal AI Assistant`)
- فعّل **Interactive features**.
- ضمن **Functionality**، حدّد **Join spaces and group conversations**.
- ضمن **Connection settings**، اختر **HTTP endpoint URL**.
- ضمن **Triggers**، اختر **Use a common HTTP endpoint URL for all triggers** واضبطه على عنوان URL العام الخاص بـ gateway متبوعًا بـ `/googlechat`.
- _نصيحة: شغّل `openclaw status` للعثور على عنوان URL العام الخاص بـ gateway._
- ضمن **Visibility**، حدّد **Make this Chat app available to specific people and groups in &lt;Your Domain&gt;**.
- أدخل عنوان بريدك الإلكتروني (مثلًا `user@example.com`) في مربع النص.
- انقر **Save** في الأسفل.
6. **فعّل حالة التطبيق**:
- بعد الحفظ، **حدّث الصفحة**.
- ابحث عن قسم **App status** (عادةً قرب الأعلى أو الأسفل بعد الحفظ).
- غيّر الحالة إلى **Live - available to users**.
- انقر **Save** مرة أخرى.
7. اضبط OpenClaw باستخدام مسار حساب الخدمة + webhook audience:
- متغير البيئة: `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json`
- أو التكوين: `channels.googlechat.serviceAccountFile: "/path/to/service-account.json"`.
8. اضبط نوع وقيمة webhook audience (بحيث يطابق إعداد تطبيق Chat لديك).
9. ابدأ gateway. سيُرسل Google Chat طلبات POST إلى مسار webhook لديك.
## الإضافة إلى Google Chat
بمجرد تشغيل gateway وإضافة بريدك الإلكتروني إلى قائمة الظهور:
1. انتقل إلى [Google Chat](https://chat.google.com/).
2. انقر على أيقونة **+** (زائد) بجانب **Direct Messages**.
3. في شريط البحث (حيث تضيف الأشخاص عادةً)، اكتب **App name** الذي قمت بتكوينه في Google Cloud Console.
- **ملاحظة**: لن يظهر الروبوت في قائمة التصفح "Marketplace" لأنه تطبيق خاص. يجب أن تبحث عنه بالاسم.
4. اختر الروبوت من النتائج.
5. انقر **Add** أو **Chat** لبدء محادثة فردية.
6. أرسل "Hello" لتشغيل المساعد!
## عنوان URL عام (Webhook فقط)
تتطلب webhooks الخاصة بـ Google Chat نقطة نهاية HTTPS عامة. لأسباب أمنية، **اكشف فقط المسار `/googlechat`** للإنترنت. أبقِ لوحة تحكم OpenClaw ونقاط النهاية الحساسة الأخرى على شبكتك الخاصة.
### الخيار A: Tailscale Funnel (موصى به)
استخدم Tailscale Serve للوحة التحكم الخاصة وFunnel لمسار webhook العام. هذا يُبقي `/` خاصًا مع كشف `/googlechat` فقط.
1. **تحقق من العنوان المرتبط به gateway:**
```bash
ss -tlnp | grep 18789
```
دوّن عنوان IP (مثلًا `127.0.0.1` أو `0.0.0.0` أو عنوان Tailscale الخاص بك مثل `100.x.x.x`).
2. **اكشف لوحة التحكم إلى tailnet فقط (المنفذ 8443):**
```bash
# If bound to localhost (127.0.0.1 or 0.0.0.0):
tailscale serve --bg --https 8443 http://127.0.0.1:18789
# If bound to Tailscale IP only (e.g., 100.106.161.80):
tailscale serve --bg --https 8443 http://100.106.161.80:18789
```
3. **اكشف مسار webhook فقط بشكل عام:**
```bash
# If bound to localhost (127.0.0.1 or 0.0.0.0):
tailscale funnel --bg --set-path /googlechat http://127.0.0.1:18789/googlechat
# If bound to Tailscale IP only (e.g., 100.106.161.80):
tailscale funnel --bg --set-path /googlechat http://100.106.161.80:18789/googlechat
```
4. **فوّض العقدة للوصول عبر Funnel:**
إذا طُلب منك ذلك، فزر عنوان URL الخاص بالتفويض الظاهر في المخرجات لتمكين Funnel لهذه العقدة في سياسة tailnet الخاصة بك.
5. **تحقق من التكوين:**
```bash
tailscale serve status
tailscale funnel status
```
سيكون عنوان URL العام لـ webhook لديك:
`https://<node-name>.<tailnet>.ts.net/googlechat`
وستبقى لوحة التحكم الخاصة بك ضمن tailnet فقط:
`https://<node-name>.<tailnet>.ts.net:8443/`
استخدم عنوان URL العام (من دون `:8443`) في إعداد تطبيق Google Chat.
> ملاحظة: يستمر هذا التكوين بعد إعادة التشغيل. لإزالته لاحقًا، شغّل `tailscale funnel reset` و`tailscale serve reset`.
### الخيار B: Reverse Proxy (Caddy)
إذا كنت تستخدم reverse proxy مثل Caddy، فقم بتمرير المسار المحدد فقط:
```caddy
your-domain.com {
reverse_proxy /googlechat* localhost:18789
}
```
مع هذا التكوين، سيتم تجاهل أي طلب إلى `your-domain.com/` أو إرجاع 404 له، بينما يتم توجيه `your-domain.com/googlechat` بأمان إلى OpenClaw.
### الخيار C: Cloudflare Tunnel
اضبط قواعد ingress الخاصة بـ tunnel لتوجيه مسار webhook فقط:
- **المسار**: `/googlechat` -> `http://localhost:18789/googlechat`
- **القاعدة الافتراضية**: HTTP 404 (غير موجود)
## كيف يعمل
1. يرسل Google Chat طلبات webhook من نوع POST إلى gateway. يتضمن كل طلب ترويسة `Authorization: Bearer <token>`.
- يتحقق OpenClaw من bearer auth قبل قراءة/تحليل أجسام webhook الكاملة عند وجود الترويسة.
- يتم دعم طلبات Google Workspace Add-on التي تحمل `authorizationEventObject.systemIdToken` في الجسم من خلال حد أقصى أكثر صرامة لجسم ما قبل المصادقة.
2. يتحقق OpenClaw من الرمز المميز مقابل `audienceType` و`audience` المكوّنين:
- `audienceType: "app-url"` → يكون audience هو عنوان URL الخاص بـ webhook عبر HTTPS.
- `audienceType: "project-number"` → يكون audience هو رقم مشروع Cloud.
3. يتم توجيه الرسائل حسب المساحة:
- تستخدم الرسائل المباشرة مفتاح الجلسة `agent:<agentId>:googlechat:direct:<spaceId>`.
- تستخدم المساحات مفتاح الجلسة `agent:<agentId>:googlechat:group:<spaceId>`.
4. يكون وصول الرسائل المباشرة عبر pairing افتراضيًا. يتلقى المرسلون غير المعروفين رمز pairing؛ وافق عليه باستخدام:
- `openclaw pairing approve googlechat <code>`
5. تتطلب المساحات الجماعية إشارة @ افتراضيًا. استخدم `botUser` إذا كان اكتشاف الإشارة يحتاج إلى اسم مستخدم التطبيق.
## الأهداف
استخدم هذه المعرّفات للتسليم وقوائم السماح:
- الرسائل المباشرة: `users/<userId>` (موصى به).
- البريد الإلكتروني الخام `name@example.com` قابل للتغيير ويُستخدم فقط لمطابقة قائمة السماح المباشرة عندما تكون `channels.googlechat.dangerouslyAllowNameMatching: true`.
- متروك: يتم التعامل مع `users/<email>` على أنه معرّف مستخدم، وليس قائمة سماح للبريد الإلكتروني.
- المساحات: `spaces/<spaceId>`.
## أبرز التكوينات
```json5
{
channels: {
googlechat: {
enabled: true,
serviceAccountFile: "/path/to/service-account.json",
// or serviceAccountRef: { source: "file", provider: "filemain", id: "/channels/googlechat/serviceAccount" }
audienceType: "app-url",
audience: "https://gateway.example.com/googlechat",
webhookPath: "/googlechat",
botUser: "users/1234567890", // optional; helps mention detection
dm: {
policy: "pairing",
allowFrom: ["users/1234567890"],
},
groupPolicy: "allowlist",
groups: {
"spaces/AAAA": {
allow: true,
requireMention: true,
users: ["users/1234567890"],
systemPrompt: "Short answers only.",
},
},
actions: { reactions: true },
typingIndicator: "message",
mediaMaxMb: 20,
},
},
}
```
ملاحظات:
- يمكن أيضًا تمرير بيانات اعتماد حساب الخدمة مباشرة باستخدام `serviceAccount` (سلسلة JSON).
- `serviceAccountRef` مدعوم أيضًا (SecretRef للبيئة/الملف)، بما في ذلك المراجع لكل حساب ضمن `channels.googlechat.accounts.<id>.serviceAccountRef`.
- مسار webhook الافتراضي هو `/googlechat` إذا لم يتم تعيين `webhookPath`.
- تعيد `dangerouslyAllowNameMatching` تمكين مطابقة principal للبريد الإلكتروني القابل للتغيير لقوائم السماح (وضع توافقية طارئ).
- تتوفر التفاعلات عبر أداة `reactions` و`channels action` عندما تكون `actions.reactions` مفعلة.
- تعرض إجراءات الرسائل `send` للنص و`upload-file` لإرسال المرفقات بشكل صريح. تقبل `upload-file` القيم `media` / `filePath` / `path` بالإضافة إلى `message` و`filename` الاختياريين واستهداف السلسلة.
- يدعم `typingIndicator` القيم `none` و`message` (الافتراضي) و`reaction` (يتطلب التفاعل OAuth للمستخدم).
- يتم تنزيل المرفقات عبر Chat API وتخزينها في مسار الوسائط (مع حد للحجم تحدده `mediaMaxMb`).
تفاصيل مرجع الأسرار: [Secrets Management](/gateway/secrets).
## استكشاف الأخطاء وإصلاحها
### 405 Method Not Allowed
إذا أظهر Google Cloud Logs Explorer أخطاء مثل:
```
status code: 405, reason phrase: HTTP error response: HTTP/1.1 405 Method Not Allowed
```
فهذا يعني أن معالج webhook غير مسجّل. الأسباب الشائعة:
1. **القناة غير مكوّنة**: قسم `channels.googlechat` مفقود من التكوين. تحقق باستخدام:
```bash
openclaw config get channels.googlechat
```
إذا أعاد "Config path not found"، فأضف التكوين (راجع [أبرز التكوينات](#config-highlights)).
2. **plugin غير مفعّل**: تحقق من حالة plugin:
```bash
openclaw plugins list | grep googlechat
```
إذا أظهر "disabled"، فأضف `plugins.entries.googlechat.enabled: true` إلى التكوين.
3. **لم تتم إعادة تشغيل gateway**: بعد إضافة التكوين، أعد تشغيل gateway:
```bash
openclaw gateway restart
```
تحقق من أن القناة تعمل:
```bash
openclaw channels status
# Should show: Google Chat default: enabled, configured, ...
```
### مشكلات أخرى
- تحقق من `openclaw channels status --probe` بحثًا عن أخطاء المصادقة أو غياب إعداد audience.
- إذا لم تصل أي رسائل، فتأكد من عنوان URL الخاص بـ webhook لتطبيق Chat واشتراكات الأحداث.
- إذا كان تقييد الإشارة يمنع الردود، فاضبط `botUser` على اسم مورد مستخدم التطبيق وتحقق من `requireMention`.
- استخدم `openclaw logs --follow` أثناء إرسال رسالة اختبار لمعرفة ما إذا كانت الطلبات تصل إلى gateway.
الوثائق ذات الصلة:
- [تكوين gateway](/gateway/configuration)
- [الأمان](/gateway/security)
- [التفاعلات](/tools/reactions)
## ذو صلة
- [نظرة عامة على القنوات](/channels) — جميع القنوات المدعومة
- [Pairing](/channels/pairing) — مصادقة الرسائل المباشرة وتدفق pairing
- [المجموعات](/channels/groups) — سلوك الدردشة الجماعية وتقييد الإشارات
- [توجيه القنوات](/channels/channel-routing) — توجيه الجلسات للرسائل
- [الأمان](/gateway/security) — نموذج الوصول والتقوية

91
docs/ar/channels/group-messages.md Normal file
View File

@ -0,0 +1,91 @@
---
read_when:
- تغيير قواعد رسائل المجموعات أو الإشارات
summary: السلوك والإعداد لمعالجة رسائل مجموعات WhatsApp (تُستخدم `mentionPatterns` عبر جميع الواجهات بشكل مشترك)
title: رسائل المجموعات
x-i18n:
generated_at: "2026-04-05T12:35:03Z"
model: gpt-5.4
provider: openai
source_hash: 2543be5bc4c6f188f955df580a6fef585ecbfc1be36ade5d34b1a9157e021bc5
source_path: channels/group-messages.md
workflow: 15
---
# رسائل المجموعات (قناة WhatsApp web)
الهدف: السماح لـ Clawd بالوجود في مجموعات WhatsApp، والاستيقاظ فقط عند مناداته، وإبقاء هذا السياق منفصلًا عن جلسة الرسائل المباشرة الشخصية.
ملاحظة: يُستخدم `agents.list[].groupChat.mentionPatterns` الآن أيضًا بواسطة Telegram/Discord/Slack/iMessage؛ يركّز هذا المستند على السلوك الخاص بـ WhatsApp. في الإعدادات متعددة الوكلاء، اضبط `agents.list[].groupChat.mentionPatterns` لكل وكيل (أو استخدم `messages.groupChat.mentionPatterns` كخيار عام احتياطي).
## التنفيذ الحالي (2025-12-03)
- أوضاع التفعيل: `mention` (الافتراضي) أو `always`. يتطلب وضع `mention` مناداة (إشارات WhatsApp @ الحقيقية عبر `mentionedJids`، أو أنماط regex الآمنة، أو رقم E.164 الخاص بالبوت في أي مكان داخل النص). يوقظ وضع `always` الوكيل عند كل رسالة، لكن يجب أن يرد فقط عندما يمكنه إضافة قيمة حقيقية؛ وإلا فإنه يعيد رمز الصمت المطابق تمامًا `NO_REPLY` / `no_reply`. يمكن ضبط القيم الافتراضية في الإعداد (`channels.whatsapp.groups`) وتجاوزها لكل مجموعة عبر `/activation`. عند ضبط `channels.whatsapp.groups`، فإنه يعمل أيضًا كقائمة سماح للمجموعات (ضمّن `"*"` للسماح للجميع).
- سياسة المجموعات: يتحكم `channels.whatsapp.groupPolicy` فيما إذا كانت رسائل المجموعات مقبولة (`open|disabled|allowlist`). يستخدم `allowlist` القيمة `channels.whatsapp.groupAllowFrom` (والخيار الاحتياطي: `channels.whatsapp.allowFrom` الصريح). القيمة الافتراضية هي `allowlist` (محظور حتى تضيف المرسلين).
- جلسات لكل مجموعة: تبدو مفاتيح الجلسات على الشكل `agent:<agentId>:whatsapp:group:<jid>` بحيث تكون أوامر مثل `/verbose on` أو `/think high` (المرسلة كرسائل مستقلة) ضمن نطاق تلك المجموعة؛ وتبقى حالة الرسائل المباشرة الشخصية دون تغيير. يتم تخطي إشارات heartbeat لخيوط المجموعات.
- حقن السياق: تُضاف رسائل المجموعات **المعلّقة فقط** (الافتراضي 50) التي _لم_ تشغّل تنفيذًا في البداية تحت `[Chat messages since your last reply - for context]`، مع السطر المشغّل تحت `[Current message - respond to this]`. لا يُعاد حقن الرسائل الموجودة بالفعل في الجلسة.
- إظهار المرسِل: تنتهي كل دفعة مجموعة الآن بـ `[from: Sender Name (+E164)]` بحيث يعرف Pi من الذي يتحدث.
- الرسائل المؤقتة/العرض لمرة واحدة: نقوم بفكها قبل استخراج النص/الإشارات، بحيث تستمر المناداة بداخلها في التفعيل.
- موجّه النظام للمجموعة: في الدورة الأولى من جلسة المجموعة (وكلما غيّر `/activation` الوضع) نضيف فقرة قصيرة إلى موجّه النظام مثل `You are replying inside the WhatsApp group "<subject>". Group members: Alice (+44...), Bob (+43...), … Activation: trigger-only … Address the specific sender noted in the message context.` وإذا لم تكن البيانات الوصفية متاحة، فما زلنا نُبلغ الوكيل بأنه في دردشة مجموعة.
## مثال على الإعداد (WhatsApp)
أضف كتلة `groupChat` إلى `~/.openclaw/openclaw.json` لكي تعمل المناداة باسم العرض حتى عندما يزيل WhatsApp الرمز المرئي `@` من نص الرسالة:
```json5
{
channels: {
whatsapp: {
groups: {
"*": { requireMention: true },
},
},
},
agents: {
list: [
{
id: "main",
groupChat: {
historyLimit: 50,
mentionPatterns: ["@?openclaw", "\\+?15555550123"],
},
},
],
},
}
```
ملاحظات:
- تعبيرات regex غير حساسة لحالة الأحرف وتستخدم حواجز الحماية نفسها الخاصة بـ safe-regex المستخدمة في واجهات regex الأخرى في الإعداد؛ ويتم تجاهل الأنماط غير الصالحة والتكرار المتداخل غير الآمن.
- لا يزال WhatsApp يرسل الإشارات القانونية عبر `mentionedJids` عندما ينقر شخص ما جهة الاتصال، لذا نادرًا ما تكون الاستعاضة بالرقم مطلوبة، لكنها تشكل شبكة أمان مفيدة.
### أمر التفعيل (للمالك فقط)
استخدم أمر دردشة المجموعة:
- `/activation mention`
- `/activation always`
يمكن فقط لرقم المالك (من `channels.whatsapp.allowFrom`، أو رقم E.164 الخاص بالبوت نفسه عند عدم الضبط) تغيير هذا. أرسل `/status` كرسالة مستقلة في المجموعة لرؤية وضع التفعيل الحالي.
## كيفية الاستخدام
1. أضف حساب WhatsApp الخاص بك (الحساب الذي يشغّل OpenClaw) إلى المجموعة.
2. قل `@openclaw …` (أو ضمّن الرقم). يمكن فقط للمرسلين المسموح لهم تشغيله ما لم تضبط `groupPolicy: "open"`.
3. سيتضمن موجّه الوكيل سياق المجموعة الحديث بالإضافة إلى العلامة اللاحقة `[from: …]` حتى يتمكن من مخاطبة الشخص الصحيح.
4. تنطبق التوجيهات على مستوى الجلسة (`/verbose on` و`/think high` و`/new` أو `/reset` و`/compact`) على جلسة تلك المجموعة فقط؛ أرسلها كرسائل مستقلة حتى يتم تسجيلها. وتبقى جلسة الرسائل المباشرة الشخصية مستقلة.
## الاختبار / التحقق
- اختبار يدوي سريع:
- أرسل مناداة `@openclaw` في المجموعة وتأكد من وجود رد يشير إلى اسم المرسل.
- أرسل مناداة ثانية وتحقق من تضمين كتلة السجل ثم مسحها في الدورة التالية.
- افحص سجلات Gateway (شغّل باستخدام `--verbose`) لرؤية إدخالات `inbound web message` التي تعرض `from: <groupJid>` واللاحقة `[from: …]`.
## اعتبارات معروفة
- يتم تخطي إشارات heartbeat عمدًا للمجموعات لتجنب البث المزعج.
- يستخدم كبح التكرار سلسلة الدفعة المجمعة؛ إذا أرسلت النص نفسه مرتين دون إشارات، فلن يحصل إلا الأول على رد.
- ستظهر إدخالات مخزن الجلسات بالشكل `agent:<agentId>:whatsapp:group:<jid>` في مخزن الجلسات (الافتراضي `~/.openclaw/agents/<agentId>/sessions/sessions.json`)؛ وغياب الإدخال يعني فقط أن المجموعة لم تشغّل تنفيذًا بعد.
- تتبع مؤشرات الكتابة في المجموعات `agents.defaults.typingMode` (الافتراضي: `message` عند عدم وجود إشارة).

417
docs/ar/channels/groups.md Normal file
View File

@ -0,0 +1,417 @@
---
read_when:
- تغيير سلوك الدردشة الجماعية أو تقييد الإشارات
summary: سلوك الدردشة الجماعية عبر الأسطح المختلفة (Discord/iMessage/Matrix/Microsoft Teams/Signal/Slack/Telegram/WhatsApp/Zalo)
title: المجموعات
x-i18n:
generated_at: "2026-04-05T12:35:28Z"
model: gpt-5.4
provider: openai
source_hash: 39d066e0542b468c6f8b384b463e2316590ea09a00ecb2065053e1e2ce55bd5f
source_path: channels/groups.md
workflow: 15
---
# المجموعات
يتعامل OpenClaw مع الدردشات الجماعية بشكل متسق عبر الأسطح المختلفة: Discord وiMessage وMatrix وMicrosoft Teams وSignal وSlack وTelegram وWhatsApp وZalo.
## مقدمة للمبتدئين (دقيقتان)
يعمل OpenClaw من خلال حسابات المراسلة الخاصة بك. لا يوجد مستخدم بوت منفصل على WhatsApp.
إذا كنت **أنت** في مجموعة، يمكن لـ OpenClaw رؤية تلك المجموعة والرد فيها.
السلوك الافتراضي:
- المجموعات مقيّدة (`groupPolicy: "allowlist"`).
- تتطلب الردود إشارة، إلا إذا عطّلت تقييد الإشارات صراحةً.
المعنى: يمكن للمرسلين المدرجين في قائمة السماح تشغيل OpenClaw عبر الإشارة إليه.
> خلاصة سريعة
>
> - يتم التحكم في **الوصول عبر الرسائل المباشرة** بواسطة `*.allowFrom`.
> - يتم التحكم في **الوصول إلى المجموعات** بواسطة `*.groupPolicy` + قوائم السماح (`*.groups`, `*.groupAllowFrom`).
> - يتم التحكم في **تشغيل الردود** بواسطة تقييد الإشارات (`requireMention`, `/activation`).
التدفق السريع (ما الذي يحدث لرسالة مجموعة):
```
groupPolicy? disabled -> drop
groupPolicy? allowlist -> group allowed? no -> drop
requireMention? yes -> mentioned? no -> store for context only
otherwise -> reply
```
## رؤية السياق وقوائم السماح
هناك عنصران مختلفان يتحكمان في أمان المجموعات:
- **تفويض التشغيل**: من يمكنه تشغيل الوكيل (`groupPolicy`, `groups`, `groupAllowFrom`, وقوائم السماح الخاصة بالقناة).
- **رؤية السياق**: ما السياق التكميلي الذي يُحقن في النموذج (نص الرد، والاقتباسات، وسجل السلسلة، وبيانات إعادة التوجيه).
بشكل افتراضي، يعطي OpenClaw الأولوية لسلوك الدردشة العادي ويحتفظ بالسياق كما تم استلامه في الغالب. وهذا يعني أن قوائم السماح تحدد أساسًا من يمكنه تشغيل الإجراءات، وليست حدًا عامًا لإخفاء كل مقتطف مقتبس أو تاريخي.
السلوك الحالي خاص بكل قناة:
- تطبق بعض القنوات بالفعل تصفية قائمة على المرسل للسياق التكميلي في مسارات محددة (مثل تهيئة سلاسل Slack وعمليات بحث الرد/السلسلة في Matrix).
- ما تزال قنوات أخرى تمرر سياق الاقتباس/الرد/إعادة التوجيه كما تم استلامه.
اتجاه التقوية (مخطط له):
- `contextVisibility: "all"` (الافتراضي) يبقي السلوك الحالي كما تم استلامه.
- `contextVisibility: "allowlist"` يرشّح السياق التكميلي إلى المرسلين المسموح لهم.
- `contextVisibility: "allowlist_quote"` هو `allowlist` مع استثناء صريح واحد للاقتباس/الرد.
إلى أن يُنفَّذ نموذج التقوية هذا بشكل متسق عبر القنوات، توقّع وجود فروق حسب السطح.
![تدفق رسائل المجموعات](/images/groups-flow.svg)
إذا كنت تريد...
| الهدف | ما الذي يجب ضبطه |
| -------------------------------------------- | -------------------------------------------------------- |
| السماح بكل المجموعات لكن الرد فقط عند @mentions | `groups: { "*": { requireMention: true } }` |
| تعطيل كل ردود المجموعات | `groupPolicy: "disabled"` |
| مجموعات محددة فقط | `groups: { "<group-id>": { ... } }` (من دون مفتاح `"*"`) |
| أنت وحدك من يمكنه التشغيل في المجموعات | `groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]` |
## مفاتيح الجلسات
- تستخدم جلسات المجموعات مفاتيح جلسات بصيغة `agent:<agentId>:<channel>:group:<id>` (أما الغرف/القنوات فتستخدم `agent:<agentId>:<channel>:channel:<id>`).
- تضيف موضوعات منتدى Telegram اللاحقة `:topic:<threadId>` إلى معرّف المجموعة بحيث يكون لكل موضوع جلسته الخاصة.
- تستخدم الدردشات المباشرة الجلسة الرئيسية (أو جلسة لكل مرسل إذا تم تكوين ذلك).
- يتم تخطي heartbeat لجلسات المجموعات.
<a id="pattern-personal-dms-public-groups-single-agent"></a>
## النمط: الرسائل المباشرة الشخصية + المجموعات العامة (وكيل واحد)
نعم — هذا يعمل جيدًا إذا كانت الحركة “الشخصية” لديك هي **الرسائل المباشرة** وكانت الحركة “العامة” لديك هي **المجموعات**.
السبب: في وضع الوكيل الواحد، تصل الرسائل المباشرة عادةً إلى مفتاح الجلسة **الرئيسية** (`agent:main:main`)، بينما تستخدم المجموعات دائمًا مفاتيح جلسات **غير رئيسية** (`agent:main:<channel>:group:<id>`). إذا فعّلت العزل باستخدام `mode: "non-main"`، فستعمل جلسات المجموعات تلك داخل Docker بينما تبقى جلسة الرسائل المباشرة الرئيسية على المضيف.
وهذا يمنحك “عقل” وكيل واحدًا (مساحة عمل + ذاكرة مشتركتان)، ولكن وضعيتين مختلفتين للتنفيذ:
- **الرسائل المباشرة**: أدوات كاملة (على المضيف)
- **المجموعات**: صندوق عزل + أدوات مراسلة مقيّدة (Docker)
> إذا كنت تحتاج إلى مساحات عمل/شخصيات منفصلة تمامًا (“الشخصي” و”العام” يجب ألا يختلطا أبدًا)، فاستخدم وكيلًا ثانيًا + ربطًا. راجع [Multi-Agent Routing](/concepts/multi-agent).
مثال (الرسائل المباشرة على المضيف، والمجموعات داخل صندوق عزل + أدوات مراسلة فقط):
```json5
{
agents: {
defaults: {
sandbox: {
mode: "non-main", // المجموعات/القنوات غير رئيسية -> داخل صندوق عزل
scope: "session", // أقوى عزل (حاوية واحدة لكل مجموعة/قناة)
workspaceAccess: "none",
},
},
},
tools: {
sandbox: {
tools: {
// إذا كانت allow غير فارغة، فسيُحظر كل شيء آخر (وdeny ما زال له الأولوية).
allow: ["group:messaging", "group:sessions"],
deny: ["group:runtime", "group:fs", "group:ui", "nodes", "cron", "gateway"],
},
},
},
}
```
هل تريد أن “تستطيع المجموعات رؤية المجلد X فقط” بدلًا من “عدم الوصول إلى المضيف”؟ أبقِ `workspaceAccess: "none"` وقم بتركيب المسارات المسموح بها فقط داخل صندوق العزل:
```json5
{
agents: {
defaults: {
sandbox: {
mode: "non-main",
scope: "session",
workspaceAccess: "none",
docker: {
binds: [
// hostPath:containerPath:mode
"/home/user/FriendsShared:/data:ro",
],
},
},
},
},
}
```
ذو صلة:
- مفاتيح الإعداد والقيم الافتراضية: [Gateway configuration](/gateway/configuration-reference#agentsdefaultssandbox)
- تصحيح سبب حظر أداة: [Sandbox vs Tool Policy vs Elevated](/gateway/sandbox-vs-tool-policy-vs-elevated)
- تفاصيل bind mounts: [Sandboxing](/gateway/sandboxing#custom-bind-mounts)
## تسميات العرض
- تستخدم تسميات واجهة المستخدم `displayName` عندما تكون متاحة، وتُنسَّق بالشكل `<channel>:<token>`.
- `#room` محجوزة للغرف/القنوات؛ وتستخدم الدردشات الجماعية `g-<slug>` (أحرف صغيرة، والمسافات تتحول إلى `-`، مع الاحتفاظ بـ `#@+._-`).
## سياسة المجموعات
تحكّم في كيفية التعامل مع رسائل المجموعات/الغرف لكل قناة:
```json5
{
channels: {
whatsapp: {
groupPolicy: "disabled", // "open" | "disabled" | "allowlist"
groupAllowFrom: ["+15551234567"],
},
telegram: {
groupPolicy: "disabled",
groupAllowFrom: ["123456789"], // معرّف مستخدم Telegram رقمي (يمكن للمعالج حل @username)
},
signal: {
groupPolicy: "disabled",
groupAllowFrom: ["+15551234567"],
},
imessage: {
groupPolicy: "disabled",
groupAllowFrom: ["chat_id:123"],
},
msteams: {
groupPolicy: "disabled",
groupAllowFrom: ["user@org.com"],
},
discord: {
groupPolicy: "allowlist",
guilds: {
GUILD_ID: { channels: { help: { allow: true } } },
},
},
slack: {
groupPolicy: "allowlist",
channels: { "#general": { allow: true } },
},
matrix: {
groupPolicy: "allowlist",
groupAllowFrom: ["@owner:example.org"],
groups: {
"!roomId:example.org": { allow: true },
"#alias:example.org": { allow: true },
},
},
},
}
```
| السياسة | السلوك |
| ------------ | ------------------------------------------------------------ |
| `"open"` | تتجاوز المجموعات قوائم السماح؛ وما يزال تقييد الإشارات مطبقًا. |
| `"disabled"` | حظر كل رسائل المجموعات بالكامل. |
| `"allowlist"`| السماح فقط للمجموعات/الغرف التي تطابق قائمة السماح المكوّنة. |
ملاحظات:
- `groupPolicy` منفصلة عن تقييد الإشارات (الذي يتطلب @mentions).
- WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo: استخدم `groupAllowFrom` (والبديل: `allowFrom` الصريح).
- تنطبق موافقات إقران الرسائل المباشرة (مدخلات المخزن `*-allowFrom`) على الوصول عبر الرسائل المباشرة فقط؛ أما تفويض مرسلي المجموعات فيبقى صريحًا عبر قوائم سماح المجموعات.
- Discord: تستخدم قائمة السماح `channels.discord.guilds.<id>.channels`.
- Slack: تستخدم قائمة السماح `channels.slack.channels`.
- Matrix: تستخدم قائمة السماح `channels.matrix.groups`. يُفضَّل استخدام معرّفات الغرف أو الأسماء المستعارة؛ فالبحث عن أسماء الغرف المنضم إليها يتم على أساس أفضل جهد، وتُتجاهل الأسماء غير المحلولة أثناء التشغيل. استخدم `channels.matrix.groupAllowFrom` لتقييد المرسلين؛ كما أن قوائم السماح `users` لكل غرفة مدعومة أيضًا.
- يتم التحكم في الرسائل المباشرة الجماعية بشكل منفصل (`channels.discord.dm.*`, `channels.slack.dm.*`).
- يمكن أن تطابق قائمة سماح Telegram معرّفات المستخدمين (`"123456789"`, `"telegram:123456789"`, `"tg:123456789"`) أو أسماء المستخدمين (`"@alice"` أو `"alice"`); وتكون البوادئ غير حساسة لحالة الأحرف.
- القيمة الافتراضية هي `groupPolicy: "allowlist"`؛ وإذا كانت قائمة سماح المجموعات فارغة، فستُحظر رسائل المجموعات.
- أمان وقت التشغيل: عندما تكون كتلة الموفر مفقودة بالكامل (`channels.<provider>` غير موجودة)، تعود سياسة المجموعات إلى وضع مغلق افتراضيًا عند الفشل (عادةً `allowlist`) بدلًا من وراثة `channels.defaults.groupPolicy`.
النموذج الذهني السريع (ترتيب التقييم لرسائل المجموعات):
1. `groupPolicy` ‏(open/disabled/allowlist)
2. قوائم سماح المجموعات (`*.groups`, `*.groupAllowFrom`, قائمة السماح الخاصة بالقناة)
3. تقييد الإشارات (`requireMention`, `/activation`)
## تقييد الإشارات (الافتراضي)
تتطلب رسائل المجموعات إشارة ما لم يتم تجاوز ذلك لكل مجموعة على حدة. تعيش القيم الافتراضية لكل نظام فرعي تحت `*.groups."*"`.
يُحتسب الرد على رسالة البوت كإشارة ضمنية (عندما تدعم القناة بيانات الرد الوصفية). ينطبق هذا على Telegram وWhatsApp وSlack وDiscord وMicrosoft Teams.
```json5
{
channels: {
whatsapp: {
groups: {
"*": { requireMention: true },
"123@g.us": { requireMention: false },
},
},
telegram: {
groups: {
"*": { requireMention: true },
"123456789": { requireMention: false },
},
},
imessage: {
groups: {
"*": { requireMention: true },
"123": { requireMention: false },
},
},
},
agents: {
list: [
{
id: "main",
groupChat: {
mentionPatterns: ["@openclaw", "openclaw", "\\+15555550123"],
historyLimit: 50,
},
},
],
},
}
```
ملاحظات:
- `mentionPatterns` هي أنماط regex آمنة وغير حساسة لحالة الأحرف؛ ويتم تجاهل الأنماط غير الصالحة وأشكال التكرار المتداخل غير الآمنة.
- الأسطح التي توفّر إشارات صريحة ما تزال تمر؛ والأنماط هي بديل احتياطي.
- تجاوز لكل وكيل: `agents.list[].groupChat.mentionPatterns` (مفيد عندما تشترك عدة وكلاء في مجموعة واحدة).
- لا يُفرض تقييد الإشارات إلا عندما يكون اكتشاف الإشارات ممكنًا (إشارات أصلية أو تكوين `mentionPatterns`).
- تعيش القيم الافتراضية لـ Discord في `channels.discord.guilds."*"` (وقابلة للتجاوز لكل خادم/قناة).
- يُغلَّف سياق سجل المجموعات بشكل موحّد عبر القنوات وهو **معلّق فقط** (الرسائل التي تم تخطيها بسبب تقييد الإشارات)؛ استخدم `messages.groupChat.historyLimit` للقيمة الافتراضية العامة و`channels.<channel>.historyLimit` (أو `channels.<channel>.accounts.*.historyLimit`) للتجاوزات. اضبط القيمة إلى `0` للتعطيل.
## قيود أدوات المجموعات/القنوات (اختياري)
تدعم بعض إعدادات القنوات تقييد الأدوات المتاحة **داخل مجموعة/غرفة/قناة محددة**.
- `tools`: السماح/المنع للأدوات على مستوى المجموعة كلها.
- `toolsBySender`: تجاوزات لكل مرسل داخل المجموعة.
استخدم بادئات مفاتيح صريحة:
`id:<senderId>`, `e164:<phone>`, `username:<handle>`, `name:<displayName>`, والرمز الشامل `"*"`.
ما تزال المفاتيح القديمة غير المسبوقة مقبولة وتُطابَق على أنها `id:` فقط.
ترتيب الحل (الأكثر تحديدًا يفوز):
1. مطابقة `toolsBySender` للمجموعة/القناة
2. `tools` للمجموعة/القناة
3. مطابقة `toolsBySender` الافتراضية (`"*"` )
4. `tools` الافتراضية (`"*"`)
مثال (Telegram):
```json5
{
channels: {
telegram: {
groups: {
"*": { tools: { deny: ["exec"] } },
"-1001234567890": {
tools: { deny: ["exec", "read", "write"] },
toolsBySender: {
"id:123456789": { alsoAllow: ["exec"] },
},
},
},
},
},
}
```
ملاحظات:
- تُطبَّق قيود أدوات المجموعات/القنوات بالإضافة إلى سياسة الأدوات العامة/الخاصة بالوكيل (وما يزال المنع له الأولوية).
- تستخدم بعض القنوات تداخلًا مختلفًا للغرف/القنوات (مثل Discord `guilds.*.channels.*` وSlack `channels.*` وMicrosoft Teams `teams.*.channels.*`).
## قوائم سماح المجموعات
عند تكوين `channels.whatsapp.groups` أو `channels.telegram.groups` أو `channels.imessage.groups`، تعمل المفاتيح كقائمة سماح للمجموعات. استخدم `"*"` للسماح بكل المجموعات مع الاستمرار في ضبط سلوك الإشارات الافتراضي.
التباس شائع: موافقة إقران الرسائل المباشرة ليست هي نفسها تفويض المجموعات.
بالنسبة إلى القنوات التي تدعم إقران الرسائل المباشرة، يفتح مخزن الإقران الرسائل المباشرة فقط. أما أوامر المجموعات فما تزال تتطلب تفويضًا صريحًا لمرسل المجموعة من قوائم السماح في الإعداد، مثل `groupAllowFrom` أو البديل الموثق في الإعداد لتلك القناة.
النوايا الشائعة (نسخ/لصق):
1. تعطيل كل ردود المجموعات
```json5
{
channels: { whatsapp: { groupPolicy: "disabled" } },
}
```
2. السماح فقط بمجموعات محددة (WhatsApp)
```json5
{
channels: {
whatsapp: {
groups: {
"123@g.us": { requireMention: true },
"456@g.us": { requireMention: false },
},
},
},
}
```
3. السماح بكل المجموعات لكن مع طلب الإشارة (بشكل صريح)
```json5
{
channels: {
whatsapp: {
groups: { "*": { requireMention: true } },
},
},
}
```
4. المالك فقط يمكنه التشغيل في المجموعات (WhatsApp)
```json5
{
channels: {
whatsapp: {
groupPolicy: "allowlist",
groupAllowFrom: ["+15551234567"],
groups: { "*": { requireMention: true } },
},
},
}
```
## التفعيل (للمالك فقط)
يمكن لمالكي المجموعات تبديل التفعيل لكل مجموعة:
- `/activation mention`
- `/activation always`
يُحدَّد المالك بواسطة `channels.whatsapp.allowFrom` (أو E.164 الخاص بالبوت نفسه عند عدم ضبطه). أرسل الأمر كرسالة مستقلة. وتتجاهل الأسطح الأخرى حاليًا `/activation`.
## حقول السياق
تضبط الحمولات الواردة من المجموعات ما يلي:
- `ChatType=group`
- `GroupSubject` (إذا كان معروفًا)
- `GroupMembers` (إذا كانوا معروفين)
- `WasMentioned` (نتيجة تقييد الإشارات)
- تتضمن موضوعات منتدى Telegram أيضًا `MessageThreadId` و`IsForum`.
ملاحظات خاصة بالقنوات:
- يمكن لـ BlueBubbles اختياريًا إثراء مشاركي مجموعات macOS غير المسمّين من قاعدة بيانات جهات الاتصال المحلية قبل تعبئة `GroupMembers`. وهذا معطّل افتراضيًا ولا يعمل إلا بعد اجتياز تقييد المجموعات العادي.
يتضمن موجه نظام الوكيل مقدمة عن المجموعات في الدور الأول من جلسة مجموعة جديدة. وهي تذكّر النموذج بالرد مثل إنسان، وتجنب جداول Markdown، وتجنب كتابة سلاسل `\n` الحرفية.
## تفاصيل iMessage
- يُفضَّل استخدام `chat_id:<id>` عند التوجيه أو الإدراج في قائمة السماح.
- عرض الدردشات: `imsg chats --limit 20`.
- تعود الردود الجماعية دائمًا إلى `chat_id` نفسه.
## تفاصيل WhatsApp
راجع [رسائل المجموعات](/channels/group-messages) للاطلاع على السلوك الخاص بـ WhatsApp فقط (حقن السجل وتفاصيل معالجة الإشارات).

434
docs/ar/channels/imessage.md Normal file
View File

@ -0,0 +1,434 @@
---
read_when:
- إعداد دعم iMessage
- تصحيح مشكلات الإرسال/الاستقبال في iMessage
summary: دعم iMessage القديم عبر imsg ‏(JSON-RPC عبر stdio). يجب أن تستخدم الإعدادات الجديدة BlueBubbles.
title: iMessage
x-i18n:
generated_at: "2026-04-05T12:35:33Z"
model: gpt-5.4
provider: openai
source_hash: 086d85bead49f75d12ae6b14ac917af52375b6afd28f6af1a0dcbbc7fcb628a0
source_path: channels/imessage.md
workflow: 15
---
# iMessage (قديم: imsg)
<Warning>
بالنسبة إلى عمليات نشر iMessage الجديدة، استخدم <a href="/channels/bluebubbles">BlueBubbles</a>.
تكامل `imsg` قديم وقد تتم إزالته في إصدار مستقبلي.
</Warning>
الحالة: تكامل CLI خارجي قديم. يقوم Gateway بتشغيل `imsg rpc` والتواصل عبر JSON-RPC على stdio (من دون daemon/port منفصل).
<CardGroup cols={3}>
<Card title="BlueBubbles (موصى به)" icon="message-circle" href="/channels/bluebubbles">
مسار iMessage المفضل للإعدادات الجديدة.
</Card>
<Card title="الاقتران" icon="link" href="/channels/pairing">
تستخدم الرسائل المباشرة في iMessage وضع الاقتران افتراضيًا.
</Card>
<Card title="مرجع الإعدادات" icon="settings" href="/gateway/configuration-reference#imessage">
مرجع كامل لحقول iMessage.
</Card>
</CardGroup>
## إعداد سريع
<Tabs>
<Tab title="Mac محلي (المسار السريع)">
<Steps>
<Step title="تثبيت imsg والتحقق منه">
```bash
brew install steipete/tap/imsg
imsg rpc --help
```
</Step>
<Step title="إعداد OpenClaw">
```json5
{
channels: {
imessage: {
enabled: true,
cliPath: "/usr/local/bin/imsg",
dbPath: "/Users/<you>/Library/Messages/chat.db",
},
},
}
```
</Step>
<Step title="بدء gateway">
```bash
openclaw gateway
```
</Step>
<Step title="الموافقة على أول اقتران رسالة مباشرة (سياسة dmPolicy الافتراضية)">
```bash
openclaw pairing list imessage
openclaw pairing approve imessage <CODE>
```
تنتهي صلاحية طلبات الاقتران بعد ساعة واحدة.
</Step>
</Steps>
</Tab>
<Tab title="Mac بعيد عبر SSH">
يحتاج OpenClaw فقط إلى `cliPath` متوافق مع stdio، لذلك يمكنك توجيه `cliPath` إلى نص wrapper برمجي يستخدم SSH إلى Mac بعيد ويشغّل `imsg`.
```bash
#!/usr/bin/env bash
exec ssh -T gateway-host imsg "$@"
```
الإعداد الموصى به عند تمكين المرفقات:
```json5
{
channels: {
imessage: {
enabled: true,
cliPath: "~/.openclaw/scripts/imsg-ssh",
remoteHost: "user@gateway-host", // يُستخدم لجلب المرفقات عبر SCP
includeAttachments: true,
// اختياري: تجاوز الجذور المسموح بها للمرفقات.
// تتضمن القيم الافتراضية /Users/*/Library/Messages/Attachments
attachmentRoots: ["/Users/*/Library/Messages/Attachments"],
remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],
},
},
}
```
إذا لم يتم ضبط `remoteHost`، يحاول OpenClaw اكتشافه تلقائيًا من خلال تحليل نص wrapper البرمجي لـ SSH.
يجب أن يكون `remoteHost` بصيغة `host` أو `user@host` (من دون مسافات أو خيارات SSH).
يستخدم OpenClaw تحققًا صارمًا من مفتاح المضيف لـ SCP، لذلك يجب أن يكون مفتاح مضيف relay موجودًا مسبقًا في `~/.ssh/known_hosts`.
يتم التحقق من مسارات المرفقات مقابل الجذور المسموح بها (`attachmentRoots` / `remoteAttachmentRoots`).
</Tab>
</Tabs>
## المتطلبات والأذونات (macOS)
- يجب أن يكون Messages مسجّل الدخول على Mac الذي يشغّل `imsg`.
- يلزم Full Disk Access لسياق العملية التي تشغّل OpenClaw/`imsg` (للوصول إلى قاعدة بيانات Messages).
- يلزم إذن Automation لإرسال الرسائل عبر Messages.app.
<Tip>
يتم منح الأذونات لكل سياق عملية. إذا كان gateway يعمل بلا واجهة (LaunchAgent/SSH)، فشغّل أمرًا تفاعليًا لمرة واحدة في السياق نفسه لتفعيل مطالبات الأذونات:
```bash
imsg chats --limit 1
# or
imsg send <handle> "test"
```
</Tip>
## التحكم في الوصول والتوجيه
<Tabs>
<Tab title="سياسة الرسائل المباشرة">
يتحكم `channels.imessage.dmPolicy` في الرسائل المباشرة:
- `pairing` (الافتراضي)
- `allowlist`
- `open` (يتطلب أن تتضمن `allowFrom` القيمة `"*"`)
- `disabled`
حقل قائمة السماح: `channels.imessage.allowFrom`.
يمكن أن تكون إدخالات قائمة السماح handles أو أهداف دردشة (`chat_id:*` أو `chat_guid:*` أو `chat_identifier:*`).
</Tab>
<Tab title="سياسة المجموعات + الإشارات">
يتحكم `channels.imessage.groupPolicy` في التعامل مع المجموعات:
- `allowlist` (الافتراضي عند الإعداد)
- `open`
- `disabled`
قائمة السماح لمرسلي المجموعات: `channels.imessage.groupAllowFrom`.
التراجع في وقت التشغيل: إذا لم يتم ضبط `groupAllowFrom`، فإن فحوصات مرسلي مجموعات iMessage تعود إلى `allowFrom` عند توفره.
ملاحظة وقت التشغيل: إذا كان `channels.imessage` مفقودًا بالكامل، يعود وقت التشغيل إلى `groupPolicy="allowlist"` ويسجل تحذيرًا (حتى إذا كان `channels.defaults.groupPolicy` مضبوطًا).
بوابة الإشارات للمجموعات:
- لا يحتوي iMessage على بيانات تعريف أصلية للإشارات
- يستخدم اكتشاف الإشارات أنماط regex ‏(`agents.list[].groupChat.mentionPatterns`، مع تراجع إلى `messages.groupChat.mentionPatterns`)
- من دون أنماط مهيأة، لا يمكن فرض بوابة الإشارات
يمكن لأوامر التحكم الواردة من مرسلين مخولين تجاوز بوابة الإشارات في المجموعات.
</Tab>
<Tab title="الجلسات والردود الحتمية">
- تستخدم الرسائل المباشرة التوجيه المباشر؛ وتستخدم المجموعات توجيه المجموعات.
- مع الإعداد الافتراضي `session.dmScope=main`، تندمج الرسائل المباشرة في iMessage ضمن الجلسة الرئيسية للوكيل.
- تكون جلسات المجموعات معزولة (`agent:<agentId>:imessage:group:<chat_id>`).
- تُوجَّه الردود مرة أخرى إلى iMessage باستخدام بيانات تعريف القناة/الهدف الأصلية.
سلوك السلاسل الشبيهة بالمجموعات:
قد تصل بعض سلاسل iMessage متعددة المشاركين مع `is_group=false`.
إذا كان هذا `chat_id` مهيأً صراحةً ضمن `channels.imessage.groups`، فإن OpenClaw يعامله كحركة مرور مجموعة (بوابة مجموعات + عزل جلسة المجموعة).
</Tab>
</Tabs>
## ارتباطات محادثات ACP
يمكن أيضًا ربط محادثات iMessage القديمة بجلسات ACP.
تدفق المشغل السريع:
- شغّل `/acp spawn codex --bind here` داخل الرسالة المباشرة أو دردشة المجموعة المسموح بها.
- تُوجَّه الرسائل المستقبلية في محادثة iMessage نفسها إلى جلسة ACP التي تم إنشاؤها.
- يعيد `/new` و`/reset` تعيين جلسة ACP المرتبطة نفسها في مكانها.
- يغلق `/acp close` جلسة ACP ويزيل الارتباط.
يتم دعم الارتباطات الدائمة المهيأة عبر إدخالات `bindings[]` من المستوى الأعلى مع `type: "acp"` و`match.channel: "imessage"`.
يمكن أن يستخدم `match.peer.id`:
- handle رسالة مباشرة مطبّعًا مثل `+15555550123` أو `user@example.com`
- `chat_id:<id>` (موصى به للارتباطات المستقرة للمجموعات)
- `chat_guid:<guid>`
- `chat_identifier:<identifier>`
مثال:
```json5
{
agents: {
list: [
{
id: "codex",
runtime: {
type: "acp",
acp: { agent: "codex", backend: "acpx", mode: "persistent" },
},
},
],
},
bindings: [
{
type: "acp",
agentId: "codex",
match: {
channel: "imessage",
accountId: "default",
peer: { kind: "group", id: "chat_id:123" },
},
acp: { label: "codex-group" },
},
],
}
```
راجع [وكلاء ACP](/tools/acp-agents) لمعرفة سلوك ارتباط ACP المشترك.
## أنماط النشر
<AccordionGroup>
<Accordion title="مستخدم macOS مخصص للبوت (هوية iMessage منفصلة)">
استخدم Apple ID ومستخدم macOS مخصصين بحيث تكون حركة مرور البوت معزولة عن ملف Messages الشخصي الخاص بك.
التدفق المعتاد:
1. أنشئ/سجّل الدخول إلى مستخدم macOS مخصص.
2. سجّل الدخول إلى Messages باستخدام Apple ID الخاص بالبوت في ذلك المستخدم.
3. ثبّت `imsg` لذلك المستخدم.
4. أنشئ wrapper لـ SSH حتى يتمكن OpenClaw من تشغيل `imsg` في سياق ذلك المستخدم.
5. وجّه `channels.imessage.accounts.<id>.cliPath` و`.dbPath` إلى ملف ذلك المستخدم.
قد يتطلب التشغيل الأول موافقات GUI ‏(Automation + Full Disk Access) في جلسة مستخدم البوت تلك.
</Accordion>
<Accordion title="Mac بعيد عبر Tailscale (مثال)">
بنية شائعة:
- يعمل gateway على Linux/VM
- يعمل iMessage و`imsg` على Mac داخل tailnet لديك
- يستخدم wrapper الخاص بـ `cliPath` ‏SSH لتشغيل `imsg`
- يتيح `remoteHost` جلب المرفقات عبر SCP
مثال:
```json5
{
channels: {
imessage: {
enabled: true,
cliPath: "~/.openclaw/scripts/imsg-ssh",
remoteHost: "bot@mac-mini.tailnet-1234.ts.net",
includeAttachments: true,
dbPath: "/Users/bot/Library/Messages/chat.db",
},
},
}
```
```bash
#!/usr/bin/env bash
exec ssh -T bot@mac-mini.tailnet-1234.ts.net imsg "$@"
```
استخدم مفاتيح SSH بحيث يكون كل من SSH وSCP غير تفاعليين.
تأكد أولًا من الوثوق بمفتاح المضيف (على سبيل المثال `ssh bot@mac-mini.tailnet-1234.ts.net`) حتى تتم تعبئة `known_hosts`.
</Accordion>
<Accordion title="نمط الحسابات المتعددة">
يدعم iMessage إعدادات لكل حساب ضمن `channels.imessage.accounts`.
يمكن لكل حساب تجاوز حقول مثل `cliPath` و`dbPath` و`allowFrom` و`groupPolicy` و`mediaMaxMb` وإعدادات السجل وقوائم السماح لجذور المرفقات.
</Accordion>
</AccordionGroup>
## الوسائط والتقسيم وأهداف التسليم
<AccordionGroup>
<Accordion title="المرفقات والوسائط">
- إدخال المرفقات الواردة اختياري: `channels.imessage.includeAttachments`
- يمكن جلب مسارات المرفقات البعيدة عبر SCP عند ضبط `remoteHost`
- يجب أن تطابق مسارات المرفقات الجذور المسموح بها:
- `channels.imessage.attachmentRoots` (محلي)
- `channels.imessage.remoteAttachmentRoots` (وضع SCP البعيد)
- نمط الجذر الافتراضي: `/Users/*/Library/Messages/Attachments`
- يستخدم SCP تحققًا صارمًا من مفتاح المضيف (`StrictHostKeyChecking=yes`)
- يستخدم حجم الوسائط الصادرة `channels.imessage.mediaMaxMb` (الافتراضي 16 MB)
</Accordion>
<Accordion title="تقسيم الرسائل الصادرة">
- حد تقسيم النص: `channels.imessage.textChunkLimit` (الافتراضي 4000)
- وضع التقسيم: `channels.imessage.chunkMode`
- `length` (الافتراضي)
- `newline` (التقسيم حسب الفقرة أولًا)
</Accordion>
<Accordion title="تنسيقات العنونة">
الأهداف الصريحة المفضلة:
- `chat_id:123` (موصى به للتوجيه المستقر)
- `chat_guid:...`
- `chat_identifier:...`
أهداف handle مدعومة أيضًا:
- `imessage:+1555...`
- `sms:+1555...`
- `user@example.com`
```bash
imsg chats --limit 20
```
</Accordion>
</AccordionGroup>
## عمليات كتابة الإعدادات
يسمح iMessage افتراضيًا بعمليات كتابة الإعدادات التي تبدأها القناة (لأوامر `/config set|unset` عندما تكون `commands.config: true`).
للتعطيل:
```json5
{
channels: {
imessage: {
configWrites: false,
},
},
}
```
## استكشاف الأخطاء وإصلاحها
<AccordionGroup>
<Accordion title="لم يتم العثور على imsg أو أن RPC غير مدعوم">
تحقّق من الملف التنفيذي ودعم RPC:
```bash
imsg rpc --help
openclaw channels status --probe
```
إذا أبلغ الفحص أن RPC غير مدعوم، فقم بتحديث `imsg`.
</Accordion>
<Accordion title="يتم تجاهل الرسائل المباشرة">
تحقّق من:
- `channels.imessage.dmPolicy`
- `channels.imessage.allowFrom`
- موافقات الاقتران (`openclaw pairing list imessage`)
</Accordion>
<Accordion title="يتم تجاهل رسائل المجموعات">
تحقّق من:
- `channels.imessage.groupPolicy`
- `channels.imessage.groupAllowFrom`
- سلوك قائمة السماح لـ `channels.imessage.groups`
- إعداد أنماط الإشارة (`agents.list[].groupChat.mentionPatterns`)
</Accordion>
<Accordion title="فشل المرفقات البعيدة">
تحقّق من:
- `channels.imessage.remoteHost`
- `channels.imessage.remoteAttachmentRoots`
- مصادقة مفاتيح SSH/SCP من مضيف gateway
- وجود مفتاح المضيف في `~/.ssh/known_hosts` على مضيف gateway
- قابلية قراءة المسار البعيد على Mac الذي يشغّل Messages
</Accordion>
<Accordion title="تم تفويت مطالبات أذونات macOS">
أعد التشغيل في طرفية GUI تفاعلية ضمن سياق المستخدم/الجلسة نفسه ووافق على المطالبات:
```bash
imsg chats --limit 1
imsg send <handle> "test"
```
أكّد منح Full Disk Access وAutomation لسياق العملية الذي يشغّل OpenClaw/`imsg`.
</Accordion>
</AccordionGroup>
## مؤشرات إلى مرجع الإعدادات
- [مرجع الإعدادات - iMessage](/gateway/configuration-reference#imessage)
- [إعدادات Gateway](/gateway/configuration)
- [الاقتران](/channels/pairing)
- [BlueBubbles](/channels/bluebubbles)
## ذو صلة
- [نظرة عامة على القنوات](/channels) — جميع القنوات المدعومة
- [الاقتران](/channels/pairing) — مصادقة الرسائل المباشرة وتدفق الاقتران
- [المجموعات](/channels/groups) — سلوك دردشات المجموعات وبوابة الإشارات
- [توجيه القنوات](/channels/channel-routing) — توجيه الجلسات للرسائل
- [الأمان](/gateway/security) — نموذج الوصول والتقوية

57
docs/ar/channels/index.md Normal file
View File

@ -0,0 +1,57 @@
---
read_when:
- تريد اختيار قناة دردشة لـ OpenClaw
- تحتاج إلى نظرة عامة سريعة على منصات المراسلة المدعومة
summary: منصات المراسلة التي يمكن لـ OpenClaw الاتصال بها
title: قنوات الدردشة
x-i18n:
generated_at: "2026-04-05T12:35:16Z"
model: gpt-5.4
provider: openai
source_hash: 246ee6f16aebe751241f00102bb435978ed21f6158385aff5d8e222e30567416
source_path: channels/index.md
workflow: 15
---
# قنوات الدردشة
يمكن لـ OpenClaw التحدث إليك عبر أي تطبيق دردشة تستخدمه بالفعل. تتصل كل قناة عبر Gateway.
النص مدعوم في كل مكان؛ أما الوسائط والتفاعلات فتختلف حسب القناة.
## القنوات المدعومة
- [BlueBubbles](/channels/bluebubbles) — **موصى به لـ iMessage**؛ يستخدم واجهة REST API لخادم BlueBubbles على macOS مع دعم كامل للميزات (إضافة مدمجة؛ التعديل، وإلغاء الإرسال، والتأثيرات، والتفاعلات، وإدارة المجموعات — التعديل معطّل حاليًا على macOS 26 Tahoe).
- [Discord](/channels/discord) — Discord Bot API + Gateway؛ يدعم الخوادم والقنوات والرسائل المباشرة.
- [Feishu](/channels/feishu) — بوت Feishu/Lark عبر WebSocket (إضافة مدمجة).
- [Google Chat](/channels/googlechat) — تطبيق Google Chat API عبر HTTP webhook.
- [iMessage (legacy)](/channels/imessage) — تكامل macOS قديم عبر CLI المسمى imsg (مهمل، استخدم BlueBubbles في الإعدادات الجديدة).
- [IRC](/channels/irc) — خوادم IRC التقليدية؛ قنوات + رسائل مباشرة مع عناصر تحكم في الاقتران/قائمة السماح.
- [LINE](/channels/line) — بوت LINE Messaging API (إضافة مدمجة).
- [Matrix](/channels/matrix) — بروتوكول Matrix (إضافة مدمجة).
- [Mattermost](/channels/mattermost) — Bot API + WebSocket؛ قنوات ومجموعات ورسائل مباشرة (إضافة مدمجة).
- [Microsoft Teams](/channels/msteams) — Bot Framework؛ دعم للمؤسسات (إضافة مدمجة).
- [Nextcloud Talk](/channels/nextcloud-talk) — دردشة مستضافة ذاتيًا عبر Nextcloud Talk (إضافة مدمجة).
- [Nostr](/channels/nostr) — رسائل مباشرة لامركزية عبر NIP-04 (إضافة مدمجة).
- [QQ Bot](/channels/qqbot) — QQ Bot API؛ دردشة خاصة ودردشة جماعية ووسائط غنية (إضافة مدمجة).
- [Signal](/channels/signal) — signal-cli؛ يركز على الخصوصية.
- [Slack](/channels/slack) — Bolt SDK؛ تطبيقات مساحات العمل.
- [Synology Chat](/channels/synology-chat) — Synology NAS Chat عبر webhooks صادرة + واردة (إضافة مدمجة).
- [Telegram](/channels/telegram) — Bot API عبر grammY؛ يدعم المجموعات.
- [Tlon](/channels/tlon) — تطبيق مراسلة قائم على Urbit (إضافة مدمجة).
- [Twitch](/channels/twitch) — دردشة Twitch عبر اتصال IRC (إضافة مدمجة).
- [Voice Call](/plugins/voice-call) — اتصالات هاتفية عبر Plivo أو Twilio (إضافة، تُثبت بشكل منفصل).
- [WebChat](/web/webchat) — واجهة Gateway WebChat عبر WebSocket.
- [WeChat](https://www.npmjs.com/package/@tencent-weixin/openclaw-weixin) — إضافة Tencent iLink Bot عبر تسجيل دخول QR؛ دردشات خاصة فقط.
- [WhatsApp](/channels/whatsapp) — الأكثر شيوعًا؛ يستخدم Baileys ويتطلب اقتران QR.
- [Zalo](/channels/zalo) — Zalo Bot API؛ تطبيق المراسلة الشائع في فيتنام (إضافة مدمجة).
- [Zalo Personal](/channels/zalouser) — حساب Zalo شخصي عبر تسجيل دخول QR (إضافة مدمجة).
## ملاحظات
- يمكن تشغيل القنوات في الوقت نفسه؛ اضبط عدة قنوات وسيقوم OpenClaw بالتوجيه حسب كل دردشة.
- غالبًا ما يكون **Telegram** هو الأسرع في الإعداد (رمز بوت بسيط). يتطلب WhatsApp اقتران QR و
يخزن حالة أكثر على القرص.
- يختلف سلوك المجموعات حسب القناة؛ راجع [المجموعات](/channels/groups).
- يتم فرض الاقتران في الرسائل المباشرة وقوائم السماح لأسباب تتعلق بالسلامة؛ راجع [الأمان](/gateway/security).
- استكشاف الأخطاء وإصلاحها: [استكشاف أخطاء القنوات وإصلاحها](/channels/troubleshooting).
- يتم توثيق موفري النماذج بشكل منفصل؛ راجع [موفرو النماذج](/providers/models).

259
docs/ar/channels/irc.md Normal file
View File

@ -0,0 +1,259 @@
---
read_when:
- تريد توصيل OpenClaw بقنوات IRC أو الرسائل الخاصة
- أنت تقوم بتكوين قوائم السماح في IRC أو سياسة المجموعات أو تقييد الإشارات
summary: إعداد إضافة IRC، وعناصر التحكم في الوصول، واستكشاف الأخطاء وإصلاحها
title: IRC
x-i18n:
generated_at: "2026-04-05T12:35:42Z"
model: gpt-5.4
provider: openai
source_hash: fceab2979db72116689c6c774d6736a8a2eee3559e3f3cf8969e673d317edd94
source_path: channels/irc.md
workflow: 15
---
# IRC
استخدم IRC عندما تريد OpenClaw في القنوات التقليدية (`#room`) والرسائل الخاصة.
يُشحن IRC كإضافة plugin، لكنه يُكوَّن في التكوين الرئيسي ضمن `channels.irc`.
## البدء السريع
1. فعّل تكوين IRC في `~/.openclaw/openclaw.json`.
2. اضبط على الأقل:
```json5
{
channels: {
irc: {
enabled: true,
host: "irc.example.com",
port: 6697,
tls: true,
nick: "openclaw-bot",
channels: ["#openclaw"],
},
},
}
```
يفضَّل استخدام خادم IRC خاص لتنسيق البوتات. وإذا كنت تستخدم عمدًا شبكة IRC عامة، فمن الخيارات الشائعة Libera.Chat وOFTC وSnoonet. تجنب القنوات العامة المتوقعة لحركة مرور القناة الخلفية الخاصة بالبوت أو السرب.
3. ابدأ/أعد تشغيل البوابة:
```bash
openclaw gateway run
```
## الإعدادات الأمنية الافتراضية
- القيمة الافتراضية لـ `channels.irc.dmPolicy` هي `"pairing"`.
- القيمة الافتراضية لـ `channels.irc.groupPolicy` هي `"allowlist"`.
- عند استخدام `groupPolicy="allowlist"`، اضبط `channels.irc.groups` لتعريف القنوات المسموح بها.
- استخدم TLS (`channels.irc.tls=true`) ما لم تكن تقبل عمدًا النقل بنص واضح.
## التحكم في الوصول
هناك "بوابتان" منفصلتان لقنوات IRC:
1. **الوصول إلى القناة** (`groupPolicy` + `groups`): ما إذا كان البوت يقبل الرسائل من القناة أصلًا.
2. **وصول المرسل** (`groupAllowFrom` / `groups["#channel"].allowFrom` لكل قناة): من المسموح له بتشغيل البوت داخل تلك القناة.
مفاتيح التكوين:
- قائمة السماح للرسائل الخاصة (وصول مرسل الرسائل الخاصة): `channels.irc.allowFrom`
- قائمة السماح لمرسلي المجموعات (وصول مرسل القناة): `channels.irc.groupAllowFrom`
- عناصر التحكم لكل قناة (القناة + المرسل + قواعد الإشارة): `channels.irc.groups["#channel"]`
- يتيح `channels.irc.groupPolicy="open"` القنوات غير المكوّنة (**مع استمرار تقييدها بالإشارات افتراضيًا**)
يجب أن تستخدم إدخالات قائمة السماح هويات مرسل مستقرة (`nick!user@host`).
مطابقة الاسم المستعار المجرد قابلة للتغيير ولا يتم تمكينها إلا عند `channels.irc.dangerouslyAllowNameMatching: true`.
### مشكلة شائعة: `allowFrom` مخصص للرسائل الخاصة، وليس للقنوات
إذا رأيت سجلات مثل:
- `irc: drop group sender alice!ident@host (policy=allowlist)`
…فهذا يعني أن المرسل غير مسموح له برسائل **المجموعة/القناة**. أصلح ذلك بإحدى الطريقتين:
- ضبط `channels.irc.groupAllowFrom` (عام لكل القنوات)، أو
- ضبط قوائم السماح للمرسلين لكل قناة: `channels.irc.groups["#channel"].allowFrom`
مثال (السماح لأي شخص في `#tuirc-dev` بالتحدث إلى البوت):
```json5
{
channels: {
irc: {
groupPolicy: "allowlist",
groups: {
"#tuirc-dev": { allowFrom: ["*"] },
},
},
},
}
```
## تشغيل الردود (الإشارات)
حتى إذا كانت القناة مسموحًا بها (عبر `groupPolicy` + `groups`) وكان المرسل مسموحًا به، فإن OpenClaw يطبّق افتراضيًا **تقييدًا بالإشارات** في سياقات المجموعات.
هذا يعني أنك قد ترى سجلات مثل `drop channel … (missing-mention)` ما لم تتضمن الرسالة نمط إشارة يطابق البوت.
لجعل البوت يرد في قناة IRC **من دون الحاجة إلى إشارة**، عطّل تقييد الإشارات لتلك القناة:
```json5
{
channels: {
irc: {
groupPolicy: "allowlist",
groups: {
"#tuirc-dev": {
requireMention: false,
allowFrom: ["*"],
},
},
},
},
}
```
أو للسماح **بكل** قنوات IRC (من دون قائمة سماح لكل قناة) مع الاستمرار في الرد من دون إشارات:
```json5
{
channels: {
irc: {
groupPolicy: "open",
groups: {
"*": { requireMention: false, allowFrom: ["*"] },
},
},
},
}
```
## ملاحظة أمنية (موصى بها للقنوات العامة)
إذا سمحت بـ `allowFrom: ["*"]` في قناة عامة، يمكن لأي شخص إرسال مطالبات إلى البوت.
لتقليل المخاطر، قيّد الأدوات لتلك القناة.
### الأدوات نفسها للجميع في القناة
```json5
{
channels: {
irc: {
groups: {
"#tuirc-dev": {
allowFrom: ["*"],
tools: {
deny: ["group:runtime", "group:fs", "gateway", "nodes", "cron", "browser"],
},
},
},
},
},
}
```
### أدوات مختلفة لكل مرسل (المالك يحصل على صلاحيات أكبر)
استخدم `toolsBySender` لتطبيق سياسة أكثر صرامة على `"*"` وسياسة أقل صرامة على اسمك المستعار:
```json5
{
channels: {
irc: {
groups: {
"#tuirc-dev": {
allowFrom: ["*"],
toolsBySender: {
"*": {
deny: ["group:runtime", "group:fs", "gateway", "nodes", "cron", "browser"],
},
"id:eigen": {
deny: ["gateway", "nodes", "cron"],
},
},
},
},
},
},
}
```
ملاحظات:
- يجب أن تستخدم مفاتيح `toolsBySender` البادئة `id:` لقيم هوية مرسل IRC:
`id:eigen` أو `id:eigen!~eigen@174.127.248.171` لمطابقة أقوى.
- لا تزال المفاتيح القديمة غير المسبوقة ببادئة مقبولة وتُطابَق على أنها `id:` فقط.
- تفوز أول سياسة مرسل مطابقة؛ و`"*"` هي البديل العام.
للمزيد حول الوصول إلى المجموعة مقابل التقييد بالإشارات (وكيفية تفاعلهما)، راجع: [/channels/groups](/channels/groups).
## NickServ
للتعريف باستخدام NickServ بعد الاتصال:
```json5
{
channels: {
irc: {
nickserv: {
enabled: true,
service: "NickServ",
password: "your-nickserv-password",
},
},
},
}
```
تسجيل اختياري لمرة واحدة عند الاتصال:
```json5
{
channels: {
irc: {
nickserv: {
register: true,
registerEmail: "bot@example.com",
},
},
},
}
```
عطّل `register` بعد تسجيل الاسم المستعار لتجنب محاولات REGISTER المتكررة.
## متغيرات البيئة
يدعم الحساب الافتراضي ما يلي:
- `IRC_HOST`
- `IRC_PORT`
- `IRC_TLS`
- `IRC_NICK`
- `IRC_USERNAME`
- `IRC_REALNAME`
- `IRC_PASSWORD`
- `IRC_CHANNELS` (مفصولة بفواصل)
- `IRC_NICKSERV_PASSWORD`
- `IRC_NICKSERV_REGISTER_EMAIL`
## استكشاف الأخطاء وإصلاحها
- إذا اتصل البوت لكنه لا يرد أبدًا في القنوات، فتحقق من `channels.irc.groups` **وأيضًا** مما إذا كان تقييد الإشارات يسقط الرسائل (`missing-mention`). إذا كنت تريده أن يرد من دون تنبيهات، فاضبط `requireMention:false` للقناة.
- إذا فشل تسجيل الدخول، فتحقق من توفر الاسم المستعار وكلمة مرور الخادم.
- إذا فشل TLS على شبكة مخصصة، فتحقق من إعدادات المضيف/المنفذ والشهادة.
## ذو صلة
- [نظرة عامة على القنوات](/channels) — جميع القنوات المدعومة
- [الإقران](/channels/pairing) — مصادقة الرسائل الخاصة وتدفق الإقران
- [المجموعات](/channels/groups) — سلوك دردشة المجموعات وتقييد الإشارات
- [توجيه القنوات](/channels/channel-routing) — توجيه الجلسات للرسائل
- [الأمان](/gateway/security) — نموذج الوصول والتقوية

232
docs/ar/channels/line.md Normal file
View File

@ -0,0 +1,232 @@
---
read_when:
- تريد توصيل OpenClaw بـ LINE
- تحتاج إلى إعداد webhook وبيانات الاعتماد الخاصة بـ LINE
- تريد خيارات رسائل خاصة بـ LINE
summary: إعداد وتكوين واستخدام plugin الخاص بـ LINE Messaging API
title: LINE
x-i18n:
generated_at: "2026-04-05T12:35:32Z"
model: gpt-5.4
provider: openai
source_hash: b4782b2aa3e8654505d7f1fd6fc112adf125b5010fc84d655d033688ded37414
source_path: channels/line.md
workflow: 15
---
# LINE
يتصل LINE بـ OpenClaw عبر LINE Messaging API. يعمل plugin كمستقبل
webhook على gateway ويستخدم channel access token وchannel secret
الخاصين بك للمصادقة.
الحالة: plugin مضمّن. الرسائل المباشرة، ودردشات المجموعات، والوسائط، والمواقع، ورسائل Flex،
ورسائل القوالب، والردود السريعة مدعومة. التفاعلات والخيوط
غير مدعومة.
## Plugin مضمّن
يأتي LINE كـ plugin مضمّن في إصدارات OpenClaw الحالية، لذا فإن
النسخ المجمعة العادية لا تحتاج إلى تثبيت منفصل.
إذا كنت تستخدم إصدارًا أقدم أو تثبيتًا مخصصًا لا يتضمن LINE، فقم بتثبيته
يدويًا:
```bash
openclaw plugins install @openclaw/line
```
نسخة محلية (عند التشغيل من مستودع git):
```bash
openclaw plugins install ./path/to/local/line-plugin
```
## الإعداد
1. أنشئ حساب LINE Developers وافتح Console:
[https://developers.line.biz/console/](https://developers.line.biz/console/)
2. أنشئ Provider (أو اختر واحدًا) وأضف قناة **Messaging API**.
3. انسخ **Channel access token** و**Channel secret** من إعدادات القناة.
4. فعّل **Use webhook** في إعدادات Messaging API.
5. اضبط عنوان URL الخاص بـ webhook على نقطة نهاية gateway لديك (يتطلب HTTPS):
```
https://gateway-host/line/webhook
```
يستجيب gateway لعملية التحقق من webhook الخاصة بـ LINE ‏(GET) وللأحداث الواردة ‏(POST).
إذا كنت بحاجة إلى مسار مخصص، فاضبط `channels.line.webhookPath` أو
`channels.line.accounts.<id>.webhookPath` وحدّث عنوان URL وفقًا لذلك.
ملاحظة أمنية:
- يعتمد التحقق من توقيع LINE على جسم الطلب (HMAC على الجسم الخام)، لذلك يطبق OpenClaw حدودًا صارمة على حجم جسم ما قبل المصادقة ومهلة زمنية قبل التحقق.
- يعالج OpenClaw أحداث webhook من بايتات الطلب الخام التي تم التحقق منها. يتم تجاهل قيم `req.body` التي حوّلتها برمجيات middleware في الطبقة العليا حفاظًا على سلامة التوقيع.
## التكوين
الحد الأدنى من التكوين:
```json5
{
channels: {
line: {
enabled: true,
channelAccessToken: "LINE_CHANNEL_ACCESS_TOKEN",
channelSecret: "LINE_CHANNEL_SECRET",
dmPolicy: "pairing",
},
},
}
```
متغيرات البيئة (للحساب الافتراضي فقط):
- `LINE_CHANNEL_ACCESS_TOKEN`
- `LINE_CHANNEL_SECRET`
ملفات token/secret:
```json5
{
channels: {
line: {
tokenFile: "/path/to/line-token.txt",
secretFile: "/path/to/line-secret.txt",
},
},
}
```
يجب أن يشير `tokenFile` و`secretFile` إلى ملفات عادية. يتم رفض الروابط الرمزية.
حسابات متعددة:
```json5
{
channels: {
line: {
accounts: {
marketing: {
channelAccessToken: "...",
channelSecret: "...",
webhookPath: "/line/marketing",
},
},
},
},
}
```
## التحكم في الوصول
تستخدم الرسائل المباشرة pairing افتراضيًا. يحصل المرسلون غير المعروفين على رمز pairing ويتم
تجاهل رسائلهم حتى تتم الموافقة عليها.
```bash
openclaw pairing list line
openclaw pairing approve line <CODE>
```
قوائم السماح والسياسات:
- `channels.line.dmPolicy`: ‏`pairing | allowlist | open | disabled`
- `channels.line.allowFrom`: معرّفات مستخدمي LINE المسموح لهم في الرسائل المباشرة
- `channels.line.groupPolicy`: ‏`allowlist | open | disabled`
- `channels.line.groupAllowFrom`: معرّفات مستخدمي LINE المسموح لهم في المجموعات
- عمليات تجاوز لكل مجموعة: `channels.line.groups.<groupId>.allowFrom`
- ملاحظة وقت التشغيل: إذا كان `channels.line` مفقودًا بالكامل، يعود وقت التشغيل إلى `groupPolicy="allowlist"` لفحوصات المجموعات (حتى إذا كان `channels.defaults.groupPolicy` معيّنًا).
معرّفات LINE حساسة لحالة الأحرف. تبدو المعرّفات الصالحة كما يلي:
- مستخدم: `U` + 32 حرفًا سداسيًا عشريًا
- مجموعة: `C` + 32 حرفًا سداسيًا عشريًا
- غرفة: `R` + 32 حرفًا سداسيًا عشريًا
## سلوك الرسائل
- يتم تقسيم النص إلى أجزاء عند 5000 حرف.
- تتم إزالة تنسيق Markdown؛ وتتحول كتل التعليمات البرمجية والجداول إلى بطاقات Flex
عندما يكون ذلك ممكنًا.
- يتم تخزين الردود المتدفقة مؤقتًا؛ ويتلقى LINE أجزاء كاملة مع
رسم متحرك للتحميل أثناء عمل الوكيل.
- يتم تقييد تنزيلات الوسائط بواسطة `channels.line.mediaMaxMb` (الافتراضي 10).
## بيانات القناة (الرسائل الغنية)
استخدم `channelData.line` لإرسال الردود السريعة أو المواقع أو بطاقات Flex أو
رسائل القوالب.
```json5
{
text: "Here you go",
channelData: {
line: {
quickReplies: ["Status", "Help"],
location: {
title: "Office",
address: "123 Main St",
latitude: 35.681236,
longitude: 139.767125,
},
flexMessage: {
altText: "Status card",
contents: {
/* Flex payload */
},
},
templateMessage: {
type: "confirm",
text: "Proceed?",
confirmLabel: "Yes",
confirmData: "yes",
cancelLabel: "No",
cancelData: "no",
},
},
},
}
```
يشحن plugin الخاص بـ LINE أيضًا أمر `/card` لإعدادات رسائل Flex المسبقة:
```
/card info "Welcome" "Thanks for joining!"
```
## دعم ACP
يدعم LINE ربط المحادثات عبر ACP ‏(Agent Communication Protocol):
- `/acp spawn <agent> --bind here` يربط دردشة LINE الحالية بجلسة ACP من دون إنشاء خيط فرعي.
- تعمل ارتباطات ACP المكوّنة وجلسات ACP النشطة المرتبطة بالمحادثة على LINE كما هو الحال في قنوات المحادثة الأخرى.
راجع [ACP agents](/tools/acp-agents) للحصول على التفاصيل.
## الوسائط الصادرة
يدعم plugin الخاص بـ LINE إرسال الصور ومقاطع الفيديو والملفات الصوتية عبر أداة رسائل الوكيل. يتم إرسال الوسائط عبر مسار التسليم الخاص بـ LINE مع معالجة مناسبة للمعاينة والتتبع:
- **الصور**: تُرسل كرسائل صور LINE مع إنشاء معاينة تلقائيًا.
- **مقاطع الفيديو**: تُرسل مع معالجة صريحة للمعاينة ونوع المحتوى.
- **الصوت**: يُرسل كرسائل صوتية LINE.
تعود عمليات إرسال الوسائط العامة إلى مسار الصور فقط الحالي عندما لا يتوفر مسار خاص بـ LINE.
## استكشاف الأخطاء وإصلاحها
- **فشل التحقق من webhook:** تأكد من أن عنوان URL الخاص بـ webhook يستخدم HTTPS وأن
`channelSecret` يطابق ما في LINE Console.
- **لا توجد أحداث واردة:** تأكد من أن مسار webhook يطابق `channels.line.webhookPath`
وأن gateway يمكن الوصول إليه من LINE.
- **أخطاء تنزيل الوسائط:** ارفع قيمة `channels.line.mediaMaxMb` إذا تجاوزت الوسائط
الحد الافتراضي.
## ذو صلة
- [نظرة عامة على القنوات](/channels) — جميع القنوات المدعومة
- [Pairing](/channels/pairing) — مصادقة الرسائل المباشرة وتدفق pairing
- [المجموعات](/channels/groups) — سلوك الدردشة الجماعية وتقييد الإشارات
- [توجيه القنوات](/channels/channel-routing) — توجيه الجلسات للرسائل
- [الأمان](/gateway/security) — نموذج الوصول والتقوية

63
docs/ar/channels/location.md Normal file
View File

@ -0,0 +1,63 @@
---
read_when:
- إضافة أو تعديل تحليل مواقع القنوات
- استخدام حقول سياق الموقع في مطالبات الوكيل أو الأدوات
summary: تحليل مواقع القنوات الواردة (Telegram/WhatsApp/Matrix) وحقول السياق
title: تحليل مواقع القنوات
x-i18n:
generated_at: "2026-04-05T12:35:18Z"
model: gpt-5.4
provider: openai
source_hash: 10061f0c109240a9e0bcab649b17f03b674e8bdf410debf3669b7b6da8189d96
source_path: channels/location.md
workflow: 15
---
# تحليل مواقع القنوات
يقوم OpenClaw بتوحيد المواقع المشتركة من قنوات الدردشة إلى:
- نص سهل القراءة يُضاف إلى نص الرسالة الواردة، و
- حقول مُهيكلة في حمولة سياق الرد التلقائي.
المدعوم حاليًا:
- **Telegram** (دبابيس المواقع + الأماكن + المواقع الحية)
- **WhatsApp** (`locationMessage` + `liveLocationMessage`)
- **Matrix** (`m.location` مع `geo_uri`)
## تنسيق النص
تُعرض المواقع كسطور واضحة من دون أقواس:
- دبوس:
- `📍 48.858844, 2.294351 ±12m`
- مكان مسمى:
- `📍 Eiffel Tower — Champ de Mars, Paris (48.858844, 2.294351 ±12m)`
- مشاركة حية:
- `🛰 الموقع الحي: 48.858844, 2.294351 ±12m`
إذا كانت القناة تتضمن تعليقًا/وصفًا، فسيُضاف في السطر التالي:
```
📍 48.858844, 2.294351 ±12m
التقِ هنا
```
## حقول السياق
عند وجود موقع، تُضاف هذه الحقول إلى `ctx`:
- `LocationLat` (رقم)
- `LocationLon` (رقم)
- `LocationAccuracy` (رقم، بالأمتار؛ اختياري)
- `LocationName` (سلسلة نصية؛ اختياري)
- `LocationAddress` (سلسلة نصية؛ اختياري)
- `LocationSource` (`pin | place | live`)
- `LocationIsLive` (منطقي)
## ملاحظات القنوات
- **Telegram**: تُعيَّن الأماكن إلى `LocationName/LocationAddress`؛ وتستخدم المواقع الحية `live_period`.
- **WhatsApp**: يُضاف `locationMessage.comment` و`liveLocationMessage.caption` كسطر التسمية التوضيحية.
- **Matrix**: يتم تحليل `geo_uri` كموقع دبوس؛ ويتم تجاهل الارتفاع وتكون قيمة `LocationIsLive` دائمًا false.

870
docs/ar/channels/matrix.md Normal file
View File

@ -0,0 +1,870 @@
---
read_when:
- إعداد Matrix في OpenClaw
- تهيئة E2EE والتحقق في Matrix
summary: حالة دعم Matrix، والإعداد، وأمثلة التهيئة
title: Matrix
x-i18n:
generated_at: "2026-04-05T12:37:35Z"
model: gpt-5.4
provider: openai
source_hash: ba5c49ad2125d97adf66b5517f8409567eff8b86e20224a32fcb940a02cb0659
source_path: channels/matrix.md
workflow: 15
---
# Matrix
Matrix هي إضافة القناة المدمجة Matrix في OpenClaw.
وهي تستخدم `matrix-js-sdk` الرسمي وتدعم الرسائل المباشرة، والغرف، وسلاسل الرسائل، والوسائط، والتفاعلات، والاستطلاعات، والموقع، وE2EE.
## الإضافة المدمجة
تأتي Matrix كإضافة مدمجة في إصدارات OpenClaw الحالية، لذلك لا تحتاج
البنيات المجمعة العادية إلى تثبيت منفصل.
إذا كنت تستخدم إصدارًا أقدم أو تثبيتًا مخصصًا يستبعد Matrix، فقم بتثبيته
يدويًا:
التثبيت من npm:
```bash
openclaw plugins install @openclaw/matrix
```
التثبيت من نسخة محلية:
```bash
openclaw plugins install ./path/to/local/matrix-plugin
```
راجع [Plugins](/tools/plugin) لمعرفة سلوك الإضافات وقواعد التثبيت.
## الإعداد
1. تأكد من توفر إضافة Matrix.
- إصدارات OpenClaw المجمعة الحالية تتضمنها بالفعل.
- يمكن للتثبيتات الأقدم/المخصصة إضافتها يدويًا باستخدام الأوامر أعلاه.
2. أنشئ حساب Matrix على خادمك المنزلي.
3. هيئ `channels.matrix` باستخدام أحد الخيارين:
- `homeserver` + `accessToken`، أو
- `homeserver` + `userId` + `password`.
4. أعد تشغيل Gateway.
5. ابدأ رسالة مباشرة مع البوت أو ادعه إلى غرفة.
مسارات الإعداد التفاعلي:
```bash
openclaw channels add
openclaw configure --section channels
```
ما الذي يطلبه معالج Matrix فعليًا:
- عنوان URL للخادم المنزلي
- طريقة المصادقة: access token أو كلمة مرور
- معرّف المستخدم فقط عند اختيار المصادقة بكلمة المرور
- اسم الجهاز اختياريًا
- ما إذا كنت تريد تمكين E2EE
- ما إذا كنت تريد تهيئة وصول غرفة Matrix الآن
سلوك المعالج المهم:
- إذا كانت متغيرات بيئة مصادقة Matrix موجودة بالفعل للحساب المحدد، وكان هذا الحساب لا يحتوي بالفعل على بيانات مصادقة محفوظة في الإعداد، فإن المعالج يعرض اختصار env ويكتب فقط `enabled: true` لذلك الحساب.
- عند إضافة حساب Matrix آخر بشكل تفاعلي، يتم تطبيع اسم الحساب الذي أدخلته إلى معرّف الحساب المستخدم في الإعداد ومتغيرات env. على سبيل المثال، تصبح `Ops Bot` هي `ops-bot`.
- تقبل مطالبات قائمة السماح للرسائل المباشرة قيم `@user:server` الكاملة مباشرة. ولا تعمل أسماء العرض إلا عندما يعثر البحث الحي في الدليل على تطابق واحد دقيق؛ وإلا يطلب منك المعالج إعادة المحاولة باستخدام معرّف Matrix كامل.
- تقبل مطالبات قائمة السماح للغرف معرّفات الغرف والأسماء المستعارة مباشرة. ويمكنها أيضًا حل أسماء الغرف المنضم إليها حيًا، لكن الأسماء غير المحلولة لا يتم الاحتفاظ بها إلا كما كُتبت أثناء الإعداد ويتم تجاهلها لاحقًا بواسطة حل قائمة السماح في وقت التشغيل. فضّل `!room:server` أو `#alias:server`.
- تستخدم هوية الغرفة/الجلسة في وقت التشغيل معرّف غرفة Matrix الثابت. ولا تُستخدم الأسماء المستعارة المعلنة للغرفة إلا كمدخلات بحث، وليس كمفتاح جلسة طويل الأمد أو هوية مجموعة ثابتة.
- لحل أسماء الغرف قبل حفظها، استخدم `openclaw channels resolve --channel matrix "Project Room"`.
إعداد أساسي قائم على الرمز المميز:
```json5
{
channels: {
matrix: {
enabled: true,
homeserver: "https://matrix.example.org",
accessToken: "syt_xxx",
dm: { policy: "pairing" },
},
},
}
```
إعداد قائم على كلمة المرور (يتم تخزين الرمز المميز مؤقتًا بعد تسجيل الدخول):
```json5
{
channels: {
matrix: {
enabled: true,
homeserver: "https://matrix.example.org",
userId: "@bot:example.org",
password: "replace-me", // pragma: allowlist secret
deviceName: "OpenClaw Gateway",
},
},
}
```
تخزن Matrix بيانات الاعتماد المؤقتة في `~/.openclaw/credentials/matrix/`.
ويستخدم الحساب الافتراضي `credentials.json`؛ وتستخدم الحسابات المسماة `credentials-<account>.json`.
المكافئات في متغيرات البيئة (تُستخدم عندما لا يكون مفتاح الإعداد مضبوطًا):
- `MATRIX_HOMESERVER`
- `MATRIX_ACCESS_TOKEN`
- `MATRIX_USER_ID`
- `MATRIX_PASSWORD`
- `MATRIX_DEVICE_ID`
- `MATRIX_DEVICE_NAME`
للحسابات غير الافتراضية، استخدم متغيرات env ضمن نطاق الحساب:
- `MATRIX_<ACCOUNT_ID>_HOMESERVER`
- `MATRIX_<ACCOUNT_ID>_ACCESS_TOKEN`
- `MATRIX_<ACCOUNT_ID>_USER_ID`
- `MATRIX_<ACCOUNT_ID>_PASSWORD`
- `MATRIX_<ACCOUNT_ID>_DEVICE_ID`
- `MATRIX_<ACCOUNT_ID>_DEVICE_NAME`
مثال للحساب `ops`:
- `MATRIX_OPS_HOMESERVER`
- `MATRIX_OPS_ACCESS_TOKEN`
وبالنسبة إلى معرّف الحساب المطبع `ops-bot`، استخدم:
- `MATRIX_OPS_X2D_BOT_HOMESERVER`
- `MATRIX_OPS_X2D_BOT_ACCESS_TOKEN`
تهرب Matrix علامات الترقيم في معرّفات الحسابات للحفاظ على متغيرات env ضمن النطاق بدون تعارضات.
على سبيل المثال، تتحول `-` إلى `_X2D_`، لذا يُحوَّل `ops-prod` إلى `MATRIX_OPS_X2D_PROD_*`.
لا يعرض المعالج التفاعلي اختصار متغيرات env إلا عندما تكون متغيرات env الخاصة بالمصادقة موجودة بالفعل ولا يكون الحساب المحدد قد حفظ بالفعل مصادقة Matrix في الإعداد.
## مثال على التهيئة
هذه تهيئة أساسية عملية مع اقتران الرسائل المباشرة، وقائمة سماح للغرف، وE2EE مفعّل:
```json5
{
channels: {
matrix: {
enabled: true,
homeserver: "https://matrix.example.org",
accessToken: "syt_xxx",
encryption: true,
dm: {
policy: "pairing",
threadReplies: "off",
},
groupPolicy: "allowlist",
groupAllowFrom: ["@admin:example.org"],
groups: {
"!roomid:example.org": {
requireMention: true,
},
},
autoJoin: "allowlist",
autoJoinAllowlist: ["!roomid:example.org"],
threadReplies: "inbound",
replyToMode: "off",
streaming: "partial",
},
},
}
```
## معاينات البث
بث الردود في Matrix اختياري.
اضبط `channels.matrix.streaming` على `"partial"` عندما تريد أن يرسل OpenClaw مسودة رد واحدة،
ويعدل هذه المسودة في مكانها أثناء توليد النموذج للنص، ثم ينهيها عند اكتمال
الرد:
```json5
{
channels: {
matrix: {
streaming: "partial",
},
},
}
```
- القيمة الافتراضية هي `streaming: "off"`. ينتظر OpenClaw الرد النهائي ثم يرسله مرة واحدة.
- ينشئ `streaming: "partial"` رسالة معاينة واحدة قابلة للتعديل لكتلة المساعد الحالية بدلًا من إرسال عدة رسائل جزئية.
- يفعّل `blockStreaming: true` رسائل تقدم Matrix منفصلة. ومع `streaming: "partial"`، تحتفظ Matrix بالمسودة الحية للكتلة الحالية وتحافظ على الكتل المكتملة كرسائل منفصلة.
- عندما تكون `streaming: "partial"` و`blockStreaming` معطلة، لا تقوم Matrix إلا بتعديل المسودة الحية وترسل الرد المكتمل عند انتهاء تلك الكتلة أو الدورة.
- إذا لم تعد المعاينة تتسع لحدث Matrix واحد، يوقف OpenClaw بث المعاينة ويرجع إلى الإرسال النهائي العادي.
- تواصل ردود الوسائط إرسال المرفقات بشكل طبيعي. وإذا تعذر إعادة استخدام معاينة قديمة بأمان، يقوم OpenClaw بتنقيحها قبل إرسال رد الوسائط النهائي.
- تعديلات المعاينة تستهلك استدعاءات إضافية إلى Matrix API. اترك البث معطلًا إذا كنت تريد السلوك الأكثر تحفظًا فيما يتعلق بحدود المعدل.
لا يقوم `blockStreaming` وحده بتمكين معاينات المسودات.
استخدم `streaming: "partial"` لتعديلات المعاينة؛ ثم أضف `blockStreaming: true` فقط إذا كنت تريد أيضًا أن تظل كتل المساعد المكتملة مرئية كرسائل تقدم منفصلة.
## التشفير والتحقق
في الغرف المشفرة (E2EE)، تستخدم أحداث الصور الصادرة `thumbnail_file` بحيث تكون معاينات الصور مشفرة إلى جانب المرفق الكامل. أما الغرف غير المشفرة فما زالت تستخدم `thumbnail_url` العادي. لا يلزم أي إعداد — تكتشف الإضافة حالة E2EE تلقائيًا.
### غرف بوت إلى بوت
افتراضيًا، يتم تجاهل رسائل Matrix القادمة من حسابات Matrix OpenClaw أخرى مهيأة.
استخدم `allowBots` عندما تريد عمدًا حركة Matrix بين الوكلاء:
```json5
{
channels: {
matrix: {
allowBots: "mentions", // true | "mentions"
groups: {
"!roomid:example.org": {
requireMention: true,
},
},
},
},
}
```
- يقبل `allowBots: true` الرسائل من حسابات Matrix bot أخرى مهيأة في الغرف المسموح بها والرسائل المباشرة.
- يقبل `allowBots: "mentions"` تلك الرسائل فقط عندما تشير بوضوح إلى هذا البوت في الغرف. وتظل الرسائل المباشرة مسموحًا بها.
- تتجاوز `groups.<room>.allowBots` الإعداد على مستوى الحساب لغرفة واحدة.
- يواصل OpenClaw تجاهل الرسائل من معرّف مستخدم Matrix نفسه لتجنب حلقات الرد الذاتي.
- لا تكشف Matrix هنا عن علامة bot أصلية؛ ويتعامل OpenClaw مع "منشأ بواسطة bot" على أنه "أرسلته حساب Matrix آخر مهيأ على Gateway OpenClaw هذا".
استخدم قوائم سماح صارمة للغرف ومتطلبات الإشارة عند تمكين حركة bot-to-bot في الغرف المشتركة.
تمكين التشفير:
```json5
{
channels: {
matrix: {
enabled: true,
homeserver: "https://matrix.example.org",
accessToken: "syt_xxx",
encryption: true,
dm: { policy: "pairing" },
},
},
}
```
التحقق من حالة التحقق:
```bash
openclaw matrix verify status
```
حالة مفصلة (تشخيصات كاملة):
```bash
openclaw matrix verify status --verbose
```
تضمين مفتاح الاسترداد المخزن في مخرجات قابلة للقراءة آليًا:
```bash
openclaw matrix verify status --include-recovery-key --json
```
تهيئة حالة cross-signing والتحقق:
```bash
openclaw matrix verify bootstrap
```
دعم الحسابات المتعددة: استخدم `channels.matrix.accounts` مع بيانات اعتماد لكل حساب و`name` اختياري. راجع [مرجع التهيئة](/gateway/configuration-reference#multi-account-all-channels) للنمط المشترك.
تشخيصات bootstrap مفصلة:
```bash
openclaw matrix verify bootstrap --verbose
```
فرض إعادة تعيين هوية cross-signing جديدة قبل bootstrap:
```bash
openclaw matrix verify bootstrap --force-reset-cross-signing
```
تحقق من هذا الجهاز باستخدام مفتاح استرداد:
```bash
openclaw matrix verify device "<your-recovery-key>"
```
تفاصيل مفصلة للتحقق من الجهاز:
```bash
openclaw matrix verify device "<your-recovery-key>" --verbose
```
التحقق من سلامة النسخ الاحتياطي لمفاتيح الغرف:
```bash
openclaw matrix verify backup status
```
تشخيصات مفصلة لسلامة النسخ الاحتياطي:
```bash
openclaw matrix verify backup status --verbose
```
استعادة مفاتيح الغرف من النسخ الاحتياطي على الخادم:
```bash
openclaw matrix verify backup restore
```
تشخيصات مفصلة للاستعادة:
```bash
openclaw matrix verify backup restore --verbose
```
احذف النسخة الاحتياطية الحالية على الخادم وأنشئ خط أساس جديدًا للنسخ الاحتياطي. وإذا تعذر تحميل
مفتاح النسخ الاحتياطي المخزن بشكل نظيف، يمكن لإعادة التعيين هذه أيضًا إعادة إنشاء التخزين السري لكي
تتمكن عمليات البدء البارد المستقبلية من تحميل مفتاح النسخ الاحتياطي الجديد:
```bash
openclaw matrix verify backup reset --yes
```
تكون جميع أوامر `verify` موجزة افتراضيًا (بما في ذلك تسجيلات SDK الداخلية الهادئة) ولا تعرض تشخيصات مفصلة إلا مع `--verbose`.
استخدم `--json` للحصول على مخرجات كاملة قابلة للقراءة آليًا عند استخدام البرامج النصية.
في الإعدادات متعددة الحسابات، تستخدم أوامر Matrix في CLI الحساب الافتراضي الضمني لـ Matrix ما لم تمرر `--account <id>`.
وإذا هيأت عدة حسابات مسماة، فاضبط أولًا `channels.matrix.defaultAccount` وإلا فإن عمليات CLI الضمنية تلك ستتوقف وتطلب منك اختيار حساب صراحة.
استخدم `--account` كلما أردت أن تستهدف عمليات التحقق أو الأجهزة حسابًا مسمى صراحة:
```bash
openclaw matrix verify status --account assistant
openclaw matrix verify backup restore --account assistant
openclaw matrix devices list --account assistant
```
عندما يكون التشفير معطلًا أو غير متاح لحساب مسمى، تشير تحذيرات Matrix وأخطاء التحقق إلى مفتاح إعداد ذلك الحساب، مثل `channels.matrix.accounts.assistant.encryption`.
### ما معنى "تم التحقق"
يتعامل OpenClaw مع جهاز Matrix هذا على أنه تم التحقق منه فقط عندما تتحقق منه هوية cross-signing الخاصة بك.
عمليًا، يكشف `openclaw matrix verify status --verbose` ثلاث إشارات ثقة:
- `Locally trusted`: هذا الجهاز موثوق به من قبل العميل الحالي فقط
- `Cross-signing verified`: يفيد SDK بأن الجهاز تم التحقق منه عبر cross-signing
- `Signed by owner`: تم توقيع الجهاز بواسطة مفتاح self-signing الخاص بك
تصبح قيمة `Verified by owner` هي `yes` فقط عند وجود تحقق cross-signing أو توقيع من المالك.
ولا تكفي الثقة المحلية وحدها لكي يتعامل OpenClaw مع الجهاز على أنه متحقق منه بالكامل.
### ماذا يفعل bootstrap
الأمر `openclaw matrix verify bootstrap` هو أمر الإصلاح والإعداد لحسابات Matrix المشفرة.
وهو ينفذ كل ما يلي بالترتيب:
- يهيئ التخزين السري، مع إعادة استخدام مفتاح استرداد موجود متى أمكن
- يهيئ cross-signing ويرفع مفاتيح cross-signing العامة الناقصة
- يحاول وسم الجهاز الحالي وتوقيعه عبر cross-signing
- ينشئ نسخة احتياطية جديدة لمفاتيح الغرف على الخادم إذا لم تكن موجودة بالفعل
إذا كان الخادم المنزلي يتطلب مصادقة تفاعلية لرفع مفاتيح cross-signing، فإن OpenClaw يحاول الرفع أولًا بلا مصادقة، ثم باستخدام `m.login.dummy`، ثم باستخدام `m.login.password` عندما تكون `channels.matrix.password` مهيأة.
استخدم `--force-reset-cross-signing` فقط عندما تريد عمدًا تجاهل هوية cross-signing الحالية وإنشاء هوية جديدة.
إذا كنت تريد عمدًا تجاهل النسخة الاحتياطية الحالية لمفاتيح الغرف وبدء
خط أساس جديد للنسخ الاحتياطي للرسائل المستقبلية، فاستخدم `openclaw matrix verify backup reset --yes`.
ولا تفعل ذلك إلا إذا كنت تقبل أن السجل المشفر القديم غير القابل للاسترداد سيظل
غير متاح، وأن OpenClaw قد يعيد إنشاء التخزين السري إذا تعذر تحميل
سر النسخ الاحتياطي الحالي بأمان.
### خط أساس جديد للنسخ الاحتياطي
إذا كنت تريد الحفاظ على عمل الرسائل المشفرة المستقبلية وتقبل فقدان السجل القديم غير القابل للاسترداد، فشغّل هذه الأوامر بالترتيب:
```bash
openclaw matrix verify backup reset --yes
openclaw matrix verify backup status --verbose
openclaw matrix verify status
```
أضف `--account <id>` إلى كل أمر عندما تريد استهداف حساب Matrix مسمى صراحة.
### سلوك بدء التشغيل
عندما تكون `encryption: true`، تضبط Matrix القيمة الافتراضية لـ `startupVerification` على `"if-unverified"`.
عند بدء التشغيل، إذا ظل هذا الجهاز غير متحقق منه، فستطلب Matrix تحققًا ذاتيًا في عميل Matrix آخر،
وستتخطى الطلبات المكررة ما دام هناك طلب قيد الانتظار بالفعل، وستطبق فترة تهدئة محلية قبل إعادة المحاولة بعد إعادة التشغيل.
وتُعاد محاولة الطلبات الفاشلة بشكل أسرع من إنشاء الطلبات الناجح افتراضيًا.
اضبط `startupVerification: "off"` لتعطيل طلبات بدء التشغيل التلقائية، أو عدّل `startupVerificationCooldownHours`
إذا كنت تريد نافذة إعادة محاولة أقصر أو أطول.
ينفذ بدء التشغيل أيضًا تمريرة bootstrap تشفيرية محافظة تلقائيًا.
تحاول هذه التمريرة أولًا إعادة استخدام التخزين السري الحالي وهوية cross-signing الحالية، وتتجنب إعادة تعيين cross-signing ما لم تشغّل مسار إصلاح bootstrap صريحًا.
إذا اكتشف بدء التشغيل حالة bootstrap معطلة وكانت `channels.matrix.password` مهيأة، يمكن لـ OpenClaw محاولة مسار إصلاح أكثر صرامة.
وإذا كان الجهاز الحالي موقعًا بالفعل من المالك، فإن OpenClaw يحافظ على تلك الهوية بدلًا من إعادة تعيينها تلقائيًا.
الترقية من إضافة Matrix العامة السابقة:
- يعيد OpenClaw تلقائيًا استخدام حساب Matrix نفسه، وaccess token نفسه، وهوية الجهاز نفسها متى أمكن.
- قبل تشغيل أي تغييرات ترحيل Matrix قابلة للتنفيذ، ينشئ OpenClaw أو يعيد استخدام لقطة استرداد ضمن `~/Backups/openclaw-migrations/`.
- إذا كنت تستخدم عدة حسابات Matrix، فاضبط `channels.matrix.defaultAccount` قبل الترقية من تخطيط التخزين المسطح القديم لكي يعرف OpenClaw أي حساب يجب أن يستقبل هذه الحالة القديمة المشتركة.
- إذا كانت الإضافة السابقة تخزن محليًا مفتاح فك تشفير النسخ الاحتياطي لمفاتيح غرف Matrix، فسيقوم بدء التشغيل أو `openclaw doctor --fix` باستيراده إلى تدفق مفتاح الاسترداد الجديد تلقائيًا.
- إذا تغير access token الخاص بـ Matrix بعد إعداد الترحيل، فإن بدء التشغيل يفحص الآن جذور تخزين تجزئة الرموز المجاورة بحثًا عن حالة استعادة قديمة معلقة قبل التخلي عن الاستعادة التلقائية للنسخ الاحتياطي.
- إذا تغير access token الخاص بـ Matrix لاحقًا للحساب نفسه والخادم المنزلي نفسه والمستخدم نفسه، فإن OpenClaw يفضل الآن إعادة استخدام جذر تخزين تجزئة الرمز الأكثر اكتمالًا بدلًا من البدء من دليل حالة Matrix فارغ.
- عند بدء تشغيل Gateway التالي، تتم استعادة مفاتيح الغرف المنسوخة احتياطيًا تلقائيًا إلى مخزن التشفير الجديد.
- إذا كانت الإضافة القديمة تحتوي على مفاتيح غرف محلية فقط ولم تُنسخ احتياطيًا مطلقًا، فسيحذر OpenClaw بوضوح. ولا يمكن تصدير هذه المفاتيح تلقائيًا من مخزن rust crypto السابق، لذلك قد يظل بعض السجل المشفر القديم غير متاح حتى تتم استعادته يدويًا.
- راجع [ترحيل Matrix](/install/migrating-matrix) للتدفق الكامل للترقية، والقيود، وأوامر الاسترداد، ورسائل الترحيل الشائعة.
تُنظم حالة وقت التشغيل المشفرة ضمن جذور لكل حساب، ولكل مستخدم، ولكل token-hash في
`~/.openclaw/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/`.
ويحتوي هذا الدليل على مخزن المزامنة (`bot-storage.json`) ومخزن التشفير (`crypto/`)،
وملف مفتاح الاسترداد (`recovery-key.json`)، ولقطة IndexedDB (`crypto-idb-snapshot.json`)،
وروابط سلاسل الرسائل (`thread-bindings.json`)، وحالة التحقق عند بدء التشغيل (`startup-verification.json`)
عندما تكون هذه الميزات قيد الاستخدام.
وعندما يتغير الرمز المميز مع بقاء هوية الحساب نفسها، يعيد OpenClaw استخدام أفضل
جذر موجود لذلك الثلاثي account/homeserver/user بحيث تظل حالة المزامنة السابقة، وحالة التشفير، وروابط سلاسل الرسائل،
وحالة التحقق عند بدء التشغيل مرئية.
### نموذج مخزن التشفير في Node
تستخدم Matrix E2EE في هذه الإضافة مسار Rust crypto الرسمي الخاص بـ `matrix-js-sdk` في Node.
ويتوقع هذا المسار تخزينًا دائمًا قائمًا على IndexedDB عندما تريد أن تستمر حالة التشفير بعد إعادة التشغيل.
يوفر OpenClaw ذلك حاليًا في Node من خلال:
- استخدام `fake-indexeddb` كطبقة واجهة IndexedDB المتوقعة من SDK
- استعادة محتويات IndexedDB الخاصة بـ Rust crypto من `crypto-idb-snapshot.json` قبل `initRustCrypto`
- حفظ محتويات IndexedDB المحدثة مرة أخرى إلى `crypto-idb-snapshot.json` بعد التهيئة وأثناء وقت التشغيل
- تسلسل استعادة اللقطة وحفظها مقابل `crypto-idb-snapshot.json` باستخدام قفل ملف استشاري حتى لا يتسابق حفظ وقت تشغيل Gateway وصيانة CLI على ملف اللقطة نفسه
هذا هو منطق توافق/تخزين، وليس تنفيذًا مخصصًا للتشفير.
ملف اللقطة هو حالة وقت تشغيل حساسة ويتم تخزينه بأذونات ملفات مقيّدة.
وبموجب نموذج أمان OpenClaw، فإن مضيف Gateway ودليل حالة OpenClaw المحلي موجودان بالفعل داخل حدود المشغل الموثوق، لذلك فهذه في الأساس مسألة متانة تشغيلية وليست حد ثقة بعيدًا مستقلًا.
تحسين مخطط له:
- إضافة دعم SecretRef لمواد مفاتيح Matrix الدائمة بحيث يمكن جلب مفاتيح الاسترداد والأسرار ذات الصلة بتشفير المخزن من موفري أسرار OpenClaw بدلًا من الملفات المحلية فقط
## إدارة الملف الشخصي
حدّث الملف الشخصي الذاتي لـ Matrix للحساب المحدد باستخدام:
```bash
openclaw matrix profile set --name "OpenClaw Assistant"
openclaw matrix profile set --avatar-url https://cdn.example.org/avatar.png
```
أضف `--account <id>` عندما تريد استهداف حساب Matrix مسمى صراحة.
تقبل Matrix عناوين URL للصور الرمزية بصيغة `mxc://` مباشرة. وعندما تمرر عنوان URL للصورة الرمزية من نوع `http://` أو `https://`، يقوم OpenClaw أولًا برفعه إلى Matrix ثم يخزن عنوان `mxc://` المحلول مرة أخرى في `channels.matrix.avatarUrl` (أو تجاوز الحساب المحدد).
## إشعارات التحقق التلقائية
تنشر Matrix الآن إشعارات دورة حياة التحقق مباشرة في غرفة التحقق الصارمة للرسائل المباشرة كرسائل `m.notice`.
ويشمل ذلك:
- إشعارات طلب التحقق
- إشعارات جاهزية التحقق (مع إرشادات صريحة "تحقق عبر emoji")
- إشعارات بدء التحقق واكتماله
- تفاصيل SAS (emoji والأرقام العشرية) عند توفرها
تُتبع طلبات التحقق الواردة من عميل Matrix آخر وتُقبل تلقائيًا بواسطة OpenClaw.
وبالنسبة إلى تدفقات التحقق الذاتي، يبدأ OpenClaw أيضًا تدفق SAS تلقائيًا عندما يصبح تحقق emoji متاحًا ويؤكد جانبه هو.
أما طلبات التحقق من مستخدم/جهاز Matrix آخر، فيقبل OpenClaw الطلب تلقائيًا ثم ينتظر استمرار تدفق SAS بشكل طبيعي.
ولا يزال عليك مقارنة SAS المكوّن من emoji أو الأرقام العشرية في عميل Matrix لديك وتأكيد "إنها متطابقة" هناك لإكمال التحقق.
لا يقبل OpenClaw تلقائيًا التدفقات المكررة التي بدأها بنفسه بشكل أعمى. ويتخطى بدء التشغيل إنشاء طلب جديد عندما يكون طلب التحقق الذاتي معلقًا بالفعل.
لا يتم تمرير إشعارات بروتوكول/نظام التحقق إلى مسار دردشة الوكيل، لذلك لا تنتج `NO_REPLY`.
### نظافة الأجهزة
يمكن أن تتراكم أجهزة Matrix القديمة التي يديرها OpenClaw على الحساب وتجعل الثقة في الغرف المشفرة أصعب في الفهم.
اعرضها باستخدام:
```bash
openclaw matrix devices list
```
أزل أجهزة OpenClaw Matrix القديمة غير المستخدمة باستخدام:
```bash
openclaw matrix devices prune-stale
```
### إصلاح الغرفة المباشرة
إذا خرجت حالة الرسائل المباشرة عن المزامنة، فقد ينتهي الأمر بـ OpenClaw مع روابط `m.direct` قديمة تشير إلى غرف فردية قديمة بدلًا من الرسالة المباشرة الحية. افحص الرابط الحالي لنظير باستخدام:
```bash
openclaw matrix direct inspect --user-id @alice:example.org
```
وأصلحه باستخدام:
```bash
openclaw matrix direct repair --user-id @alice:example.org
```
يبقي تدفق الإصلاح منطق Matrix الخاص داخل الإضافة:
- يفضل رسالة مباشرة 1:1 صارمة تم ربطها بالفعل في `m.direct`
- وإلا يعود إلى أي رسالة مباشرة 1:1 صارمة منضم إليها حاليًا مع ذلك المستخدم
- وإذا لم توجد رسالة مباشرة سليمة، فإنه ينشئ غرفة مباشرة جديدة ويعيد كتابة `m.direct` للإشارة إليها
لا يحذف تدفق الإصلاح الغرف القديمة تلقائيًا. إنه يختار فقط الرسالة المباشرة السليمة ويحدث الربط بحيث تستهدف عمليات إرسال Matrix الجديدة، وإشعارات التحقق، وتدفقات الرسائل المباشرة الأخرى الغرفة الصحيحة مرة أخرى.
## سلاسل الرسائل
تدعم Matrix سلاسل Matrix الأصلية لكل من الردود التلقائية ورسائل أدوات الإرسال.
- يبقي `threadReplies: "off"` الردود في المستوى الأعلى ويبقي الرسائل الواردة المترابطة على جلسة الأصل.
- يرد `threadReplies: "inbound"` داخل سلسلة فقط عندما تكون الرسالة الواردة بالفعل في تلك السلسلة.
- يبقي `threadReplies: "always"` ردود الغرفة داخل سلسلة متجذرة في الرسالة المشغلة ويوجه تلك المحادثة عبر الجلسة المطابقة ذات النطاق الخاص بالسلسلة من أول رسالة مشغلة.
- تتجاوز `dm.threadReplies` الإعداد الأعلى مستوى للرسائل المباشرة فقط. على سبيل المثال، يمكنك إبقاء سلاسل الغرف معزولة مع إبقاء الرسائل المباشرة مسطحة.
- تتضمن الرسائل الواردة ضمن السلاسل رسالة جذر السلسلة كسياق إضافي للوكيل.
- ترث رسائل أدوات الإرسال الآن سلسلة Matrix الحالية تلقائيًا عندما يكون الهدف هو الغرفة نفسها، أو هدف مستخدم الرسائل المباشرة نفسه، ما لم يتم توفير `threadId` صراحة.
- الروابط التشغيلية لسلاسل الرسائل مدعومة في Matrix. تعمل الآن `/focus` و`/unfocus` و`/agents` و`/session idle` و`/session max-age` و`/acp spawn` المرتبطة بالسلسلة في غرف Matrix والرسائل المباشرة.
- ينشئ `/focus` في غرفة/رسالة مباشرة Matrix من المستوى الأعلى سلسلة Matrix جديدة ويربطها بالجلسة الهدف عندما تكون `threadBindings.spawnSubagentSessions=true`.
- يؤدي تشغيل `/focus` أو `/acp spawn --thread here` داخل سلسلة Matrix موجودة إلى ربط تلك السلسلة الحالية بدلًا من ذلك.
## روابط محادثات ACP
يمكن تحويل غرف Matrix والرسائل المباشرة وسلاسل Matrix الموجودة إلى مساحات عمل ACP دائمة دون تغيير واجهة الدردشة.
تدفق مشغل سريع:
- شغّل `/acp spawn codex --bind here` داخل رسالة Matrix المباشرة، أو الغرفة، أو السلسلة الموجودة التي تريد الاستمرار في استخدامها.
- في رسالة Matrix مباشرة أو غرفة من المستوى الأعلى، تظل الرسالة المباشرة/الغرفة الحالية هي واجهة الدردشة وتوجَّه الرسائل المستقبلية إلى جلسة ACP التي تم إنشاؤها.
- داخل سلسلة Matrix موجودة، يربط `--bind here` تلك السلسلة الحالية في مكانها.
- يعيد `/new` و`/reset` تعيين جلسة ACP المرتبطة نفسها في مكانها.
- يغلق `/acp close` جلسة ACP ويزيل الربط.
ملاحظات:
- لا ينشئ `--bind here` سلسلة Matrix فرعية.
- لا تكون `threadBindings.spawnAcpSessions` مطلوبة إلا لـ `/acp spawn --thread auto|here`، حيث يحتاج OpenClaw إلى إنشاء سلسلة Matrix فرعية أو ربطها.
### تهيئة ربط السلاسل
ترث Matrix القيم الافتراضية العامة من `session.threadBindings`، كما تدعم تجاوزات لكل قناة:
- `threadBindings.enabled`
- `threadBindings.idleHours`
- `threadBindings.maxAgeHours`
- `threadBindings.spawnSubagentSessions`
- `threadBindings.spawnAcpSessions`
علامات إنشاء العمليات المرتبطة بالسلاسل في Matrix اختيارية:
- اضبط `threadBindings.spawnSubagentSessions: true` للسماح للأمر `/focus` في المستوى الأعلى بإنشاء سلاسل Matrix جديدة وربطها.
- اضبط `threadBindings.spawnAcpSessions: true` للسماح للأمر `/acp spawn --thread auto|here` بربط جلسات ACP بسلاسل Matrix.
## التفاعلات
تدعم Matrix إجراءات التفاعل الصادرة، وإشعارات التفاعل الواردة، وتفاعلات الإقرار الواردة.
- تخضع أدوات التفاعل الصادر للبوابة `channels["matrix"].actions.reactions`.
- يضيف `react` تفاعلًا إلى حدث Matrix محدد.
- تسرد `reactions` ملخص التفاعلات الحالي لحدث Matrix محدد.
- تؤدي `emoji=""` إلى إزالة تفاعلات حساب البوت نفسه على ذلك الحدث.
- تؤدي `remove: true` إلى إزالة تفاعل emoji المحدد فقط من حساب البوت.
يستخدم نطاق تفاعلات الإقرار ترتيب حل OpenClaw القياسي:
- `channels["matrix"].accounts.<accountId>.ackReaction`
- `channels["matrix"].ackReaction`
- `messages.ackReaction`
- الرجوع الاحتياطي إلى emoji الخاص بهوية الوكيل
يُحل نطاق تفاعلات الإقرار بهذا الترتيب:
- `channels["matrix"].accounts.<accountId>.ackReactionScope`
- `channels["matrix"].ackReactionScope`
- `messages.ackReactionScope`
يُحل وضع إشعارات التفاعل بهذا الترتيب:
- `channels["matrix"].accounts.<accountId>.reactionNotifications`
- `channels["matrix"].reactionNotifications`
- الافتراضي: `own`
السلوك الحالي:
- يؤدي `reactionNotifications: "own"` إلى تمرير أحداث `m.reaction` المضافة عندما تستهدف رسائل Matrix التي أنشأها البوت.
- يؤدي `reactionNotifications: "off"` إلى تعطيل أحداث نظام التفاعل.
- لا تزال إزالة التفاعلات غير تُركّب كأحداث نظام لأن Matrix تعرضها كتنقيحات، وليس كعمليات إزالة `m.reaction` مستقلة.
## سياق السجل
- يتحكم `channels.matrix.historyLimit` في عدد رسائل الغرف الحديثة التي تُضمَّن كـ `InboundHistory` عندما تشغّل رسالة غرفة Matrix الوكيل.
- ويرجع احتياطيًا إلى `messages.groupChat.historyLimit`. اضبطه على `0` للتعطيل.
- يكون سجل غرف Matrix خاصًا بالغرفة فقط. وتستمر الرسائل المباشرة باستخدام سجل الجلسة العادي.
- سجل غرف Matrix يكون للمعلّق فقط: يخزّن OpenClaw رسائل الغرفة التي لم تشغّل ردًا بعد، ثم يلتقط هذه النافذة عندما تصل إشارة أو مشغّل آخر.
- لا تُضمَّن رسالة المشغّل الحالية في `InboundHistory`؛ بل تبقى في نص الإدخال الرئيسي لتلك الدورة.
- تعيد محاولات الحدث Matrix نفسه استخدام لقطة السجل الأصلية بدلًا من الانجراف إلى رسائل غرفة أحدث.
## ظهور السياق
تدعم Matrix عنصر التحكم المشترك `contextVisibility` للسياق الإضافي للغرفة مثل نص الرد المجتلب، وجذور السلاسل، والسجل المعلّق.
- `contextVisibility: "all"` هي القيمة الافتراضية. ويتم الاحتفاظ بالسياق الإضافي كما ورد.
- يقوم `contextVisibility: "allowlist"` بتصفية السياق الإضافي إلى المرسلين المسموح لهم بواسطة فحوصات قائمة سماح الغرفة/المستخدم النشطة.
- يتصرف `contextVisibility: "allowlist_quote"` مثل `allowlist`، لكنه يحتفظ مع ذلك برد مقتبس صريح واحد.
يؤثر هذا الإعداد في ظهور السياق الإضافي، وليس في ما إذا كانت الرسالة الواردة نفسها يمكن أن تشغّل ردًا.
ولا يزال تفويض التشغيل يأتي من إعدادات `groupPolicy` و`groups` و`groupAllowFrom` وسياسات الرسائل المباشرة.
## مثال على سياسة الرسائل المباشرة والغرف
```json5
{
channels: {
matrix: {
dm: {
policy: "allowlist",
allowFrom: ["@admin:example.org"],
threadReplies: "off",
},
groupPolicy: "allowlist",
groupAllowFrom: ["@admin:example.org"],
groups: {
"!roomid:example.org": {
requireMention: true,
},
},
},
},
}
```
راجع [Groups](/channels/groups) لمعرفة سلوك بوابة الإشارات وقائمة السماح.
مثال اقتران لرسائل Matrix المباشرة:
```bash
openclaw pairing list matrix
openclaw pairing approve matrix <CODE>
```
إذا استمر مستخدم Matrix غير معتمد في مراسلتك قبل الموافقة، يعيد OpenClaw استخدام رمز الاقتران المعلق نفسه وقد يرسل رد تذكير مرة أخرى بعد فترة تهدئة قصيرة بدلًا من إنشاء رمز جديد.
راجع [Pairing](/channels/pairing) للتدفق المشترك لاقتران الرسائل المباشرة وتخطيط التخزين.
## موافقات exec
يمكن لـ Matrix أن تعمل كعميل موافقات exec لحساب Matrix.
- `channels.matrix.execApprovals.enabled`
- `channels.matrix.execApprovals.approvers` (اختياري؛ يرجع احتياطيًا إلى `channels.matrix.dm.allowFrom`)
- `channels.matrix.execApprovals.target` (`dm` | `channel` | `both`، الافتراضي: `dm`)
- `channels.matrix.execApprovals.agentFilter`
- `channels.matrix.execApprovals.sessionFilter`
يجب أن يكون الموافقون معرّفات مستخدمي Matrix مثل `@owner:example.org`. تقوم Matrix بتمكين موافقات exec الأصلية تلقائيًا عندما تكون `enabled` غير مضبوطة أو `"auto"` وعندما يمكن حل موافق واحد على الأقل، إما من `execApprovals.approvers` أو من `channels.matrix.dm.allowFrom`. اضبط `enabled: false` لتعطيل Matrix كعميل موافقات أصلي صراحة. وبخلاف ذلك، تعود طلبات الموافقة احتياطيًا إلى مسارات الموافقة المهيأة الأخرى أو إلى سياسة الرجوع الاحتياطي لموافقات exec.
التوجيه الأصلي في Matrix يقتصر اليوم على exec فقط:
- تتحكم `channels.matrix.execApprovals.*` في التوجيه الأصلي للرسائل المباشرة/القنوات لموافقات exec فقط.
- لا تزال موافقات الإضافات تستخدم `/approve` المشترك في الدردشة نفسها بالإضافة إلى أي إعادة توجيه مهيأة في `approvals.plugin`.
- لا يزال بإمكان Matrix إعادة استخدام `channels.matrix.dm.allowFrom` لتفويض موافقات الإضافات عندما تتمكن من استنتاج الموافقين بأمان، لكنها لا تعرض مسار توزيع أصلي منفصل لموافقات الإضافات عبر الرسائل المباشرة/القنوات.
قواعد التسليم:
- يؤدي `target: "dm"` إلى إرسال مطالبات الموافقة إلى الرسائل المباشرة للموافقين
- يؤدي `target: "channel"` إلى إعادة إرسال المطالبة إلى غرفة أو رسالة Matrix المباشرة الأصلية
- يؤدي `target: "both"` إلى الإرسال إلى الرسائل المباشرة للموافقين وإلى غرفة أو رسالة Matrix المباشرة الأصلية
تستخدم Matrix اليوم مطالبات موافقة نصية. ويعالجها الموافقون باستخدام `/approve <id> allow-once` أو `/approve <id> allow-always` أو `/approve <id> deny`.
يمكن فقط للموافقين الذين تم حلهم الموافقة أو الرفض. ويتضمن التسليم عبر القنوات نص الأمر، لذلك لا تمكّن `channel` أو `both` إلا في الغرف الموثوقة.
تعيد مطالبات موافقة Matrix استخدام مخطط الموافقات الأساسي المشترك. أما الواجهة الأصلية الخاصة بـ Matrix فهي مجرد وسيلة نقل لموافقات exec: توجيه الغرف/الرسائل المباشرة وسلوك إرسال/تحديث/حذف الرسائل.
تجاوز لكل حساب:
- `channels.matrix.accounts.<account>.execApprovals`
مستندات ذات صلة: [Exec approvals](/tools/exec-approvals)
## مثال على تعدد الحسابات
```json5
{
channels: {
matrix: {
enabled: true,
defaultAccount: "assistant",
dm: { policy: "pairing" },
accounts: {
assistant: {
homeserver: "https://matrix.example.org",
accessToken: "syt_assistant_xxx",
encryption: true,
},
alerts: {
homeserver: "https://matrix.example.org",
accessToken: "syt_alerts_xxx",
dm: {
policy: "allowlist",
allowFrom: ["@ops:example.org"],
threadReplies: "off",
},
},
},
},
},
}
```
تعمل القيم في `channels.matrix` من المستوى الأعلى كقيم افتراضية للحسابات المسماة ما لم يتجاوزها حساب ما.
يمكنك تقييد إدخالات الغرف الموروثة إلى حساب Matrix واحد باستخدام `groups.<room>.account` (أو `rooms.<room>.account` القديم).
وتظل الإدخالات التي لا تحتوي على `account` مشتركة بين جميع حسابات Matrix، كما أن الإدخالات التي تحتوي على `account: "default"` تظل تعمل عندما يكون الحساب الافتراضي مهيأ مباشرة على `channels.matrix.*` من المستوى الأعلى.
ولا تنشئ القيم الافتراضية المشتركة الجزئية للمصادقة حسابًا افتراضيًا ضمنيًا منفصلًا بمفردها. لا يقوم OpenClaw بتوليف الحساب `default` في المستوى الأعلى إلا عندما يمتلك ذلك الافتراضي مصادقة حديثة (`homeserver` مع `accessToken`، أو `homeserver` مع `userId` و`password`)؛ ويمكن للحسابات المسماة أن تظل قابلة للاكتشاف من `homeserver` مع `userId` عندما تلبّي بيانات الاعتماد المخزنة مؤقتًا المصادقة لاحقًا.
إذا كانت Matrix تحتوي بالفعل على حساب مسمى واحد بالضبط، أو كانت `defaultAccount` تشير إلى مفتاح حساب مسمى موجود، فإن ترقية الإصلاح/الإعداد من حساب واحد إلى عدة حسابات تحافظ على ذلك الحساب بدلًا من إنشاء إدخال جديد `accounts.default`. ولا تنتقل إلى ذلك الحساب المُرقّى إلا مفاتيح Matrix الخاصة بالمصادقة/bootstrap؛ أما مفاتيح سياسات التسليم المشتركة فتبقى في المستوى الأعلى.
اضبط `defaultAccount` عندما تريد أن يفضّل OpenClaw حساب Matrix مسمى واحدًا للتوجيه الضمني، والفحص، وعمليات CLI.
إذا هيأت عدة حسابات مسماة، فاضبط `defaultAccount` أو مرر `--account <id>` لأوامر CLI التي تعتمد على اختيار الحساب الضمني.
مرر `--account <id>` إلى `openclaw matrix verify ...` و`openclaw matrix devices ...` عندما تريد تجاوز هذا الاختيار الضمني لأمر واحد.
## الخوادم المنزلية الخاصة/الشبكات المحلية
افتراضيًا، يمنع OpenClaw خوادم Matrix المنزلية الخاصة/الداخلية للحماية من SSRF ما لم
توافق صراحة لكل حساب.
إذا كان خادمك المنزلي يعمل على localhost أو عنوان IP ضمن LAN/Tailscale أو اسم مضيف داخلي، فقم بتمكين
`allowPrivateNetwork` لذلك الحساب في Matrix:
```json5
{
channels: {
matrix: {
homeserver: "http://matrix-synapse:8008",
allowPrivateNetwork: true,
accessToken: "syt_internal_xxx",
},
},
}
```
مثال إعداد عبر CLI:
```bash
openclaw matrix account add \
--account ops \
--homeserver http://matrix-synapse:8008 \
--allow-private-network \
--access-token syt_ops_xxx
```
تسمح هذه الموافقة فقط بالأهداف الخاصة/الداخلية الموثوقة. أما الخوادم المنزلية العامة غير المشفرة مثل
`http://matrix.example.org:8008` فتظل محظورة. ويفضل استخدام `https://` كلما أمكن.
## تمرير حركة Matrix عبر وكيل
إذا كان نشر Matrix لديك يحتاج إلى وكيل HTTP(S) صادر صريح، فاضبط `channels.matrix.proxy`:
```json5
{
channels: {
matrix: {
homeserver: "https://matrix.example.org",
accessToken: "syt_bot_xxx",
proxy: "http://127.0.0.1:7890",
},
},
}
```
يمكن للحسابات المسماة تجاوز الافتراضي في المستوى الأعلى باستخدام `channels.matrix.accounts.<id>.proxy`.
ويستخدم OpenClaw إعداد الوكيل نفسه لحركة Matrix في وقت التشغيل ولفحوصات حالة الحساب.
## حل الأهداف
تقبل Matrix صيغ الأهداف التالية أينما طلب منك OpenClaw هدف غرفة أو مستخدم:
- المستخدمون: `@user:server` أو `user:@user:server` أو `matrix:user:@user:server`
- الغرف: `!room:server` أو `room:!room:server` أو `matrix:room:!room:server`
- الأسماء المستعارة: `#alias:server` أو `channel:#alias:server` أو `matrix:channel:#alias:server`
يستخدم البحث الحي في الدليل حساب Matrix المسجل دخوله:
- تستعلم عمليات البحث عن المستخدمين دليل مستخدمي Matrix على ذلك الخادم المنزلي.
- تقبل عمليات البحث عن الغرف معرّفات الغرف والأسماء المستعارة الصريحة مباشرة، ثم تعود احتياطيًا إلى البحث في أسماء الغرف المنضم إليها لذلك الحساب.
- يكون البحث في أسماء الغرف المنضم إليها بأفضل جهد. وإذا تعذر حل اسم الغرفة إلى معرّف أو اسم مستعار، فسيتم تجاهله بواسطة حل قائمة السماح في وقت التشغيل.
## مرجع التهيئة
- `enabled`: تمكين القناة أو تعطيلها.
- `name`: تسمية اختيارية للحساب.
- `defaultAccount`: معرّف الحساب المفضل عند تهيئة عدة حسابات Matrix.
- `homeserver`: عنوان URL للخادم المنزلي، مثل `https://matrix.example.org`.
- `allowPrivateNetwork`: السماح لهذا الحساب في Matrix بالاتصال بخوادم منزلية خاصة/داخلية. فعّل هذا عندما يُحل الخادم المنزلي إلى `localhost` أو عنوان IP ضمن LAN/Tailscale أو مضيف داخلي مثل `matrix-synapse`.
- `proxy`: عنوان URL اختياري لوكيل HTTP(S) لحركة Matrix. ويمكن للحسابات المسماة تجاوز الافتراضي في المستوى الأعلى عبر `proxy` خاص بها.
- `userId`: معرّف مستخدم Matrix كامل، مثل `@bot:example.org`.
- `accessToken`: access token للمصادقة القائمة على الرمز المميز. تُدعم القيم النصية الصريحة وقيم SecretRef لكل من `channels.matrix.accessToken` و`channels.matrix.accounts.<id>.accessToken` عبر موفري env/file/exec. راجع [Secrets Management](/gateway/secrets).
- `password`: كلمة المرور لتسجيل الدخول القائم على كلمة المرور. تُدعم القيم النصية الصريحة وقيم SecretRef.
- `deviceId`: معرّف جهاز Matrix صريح.
- `deviceName`: اسم عرض الجهاز لتسجيل الدخول بكلمة المرور.
- `avatarUrl`: عنوان URL للصورة الرمزية الذاتية المخزن لمزامنة الملف الشخصي وتحديثات `set-profile`.
- `initialSyncLimit`: حد أحداث المزامنة عند بدء التشغيل.
- `encryption`: تمكين E2EE.
- `allowlistOnly`: فرض سلوك قائمة السماح فقط على الرسائل المباشرة والغرف.
- `allowBots`: السماح بالرسائل من حسابات Matrix OpenClaw أخرى مهيأة (`true` أو `"mentions"`).
- `groupPolicy`: `open` أو `allowlist` أو `disabled`.
- `contextVisibility`: وضع ظهور السياق الإضافي للغرفة (`all` أو `allowlist` أو `allowlist_quote`).
- `groupAllowFrom`: قائمة سماح لمعرّفات المستخدمين لحركة الغرف.
- يجب أن تكون إدخالات `groupAllowFrom` معرّفات مستخدم Matrix كاملة. ويتم تجاهل الأسماء غير المحلولة في وقت التشغيل.
- `historyLimit`: الحد الأقصى لرسائل الغرف المضمّنة كسياق سجل للمجموعات. يرجع احتياطيًا إلى `messages.groupChat.historyLimit`. اضبط `0` للتعطيل.
- `replyToMode`: `off` أو `first` أو `all`.
- `markdown`: تهيئة Markdown اختيارية لتصيير نص Matrix الصادر.
- `streaming`: `off` (الافتراضي) أو `partial` أو `true` أو `false`. تؤدي `partial` و`true` إلى تمكين معاينات مسودة أحادية الرسالة مع تحديثات تعديل في المكان.
- `blockStreaming`: يؤدي `true` إلى تمكين رسائل تقدم منفصلة للكتل المكتملة للمساعد أثناء تفعيل بث معاينة المسودة.
- `threadReplies`: `off` أو `inbound` أو `always`.
- `threadBindings`: تجاوزات لكل قناة لتوجيه الجلسات المرتبطة بالسلاسل ودورة حياتها.
- `startupVerification`: وضع طلب التحقق الذاتي التلقائي عند بدء التشغيل (`if-unverified` أو `off`).
- `startupVerificationCooldownHours`: فترة التهدئة قبل إعادة محاولة طلبات التحقق التلقائية عند بدء التشغيل.
- `textChunkLimit`: حجم تجزئة الرسائل الصادرة.
- `chunkMode`: `length` أو `newline`.
- `responsePrefix`: بادئة رسائل اختيارية للردود الصادرة.
- `ackReaction`: تجاوز اختياري لتفاعل الإقرار لهذه القناة/الحساب.
- `ackReactionScope`: تجاوز اختياري لنطاق تفاعل الإقرار (`group-mentions` أو `group-all` أو `direct` أو `all` أو `none` أو `off`).
- `reactionNotifications`: وضع إشعارات التفاعل الواردة (`own` أو `off`).
- `mediaMaxMb`: الحد الأقصى لحجم الوسائط بالميغابايت لمعالجة وسائط Matrix. ويُطبّق على الإرسال الصادر ومعالجة الوسائط الواردة.
- `autoJoin`: سياسة الانضمام التلقائي للدعوات (`always` أو `allowlist` أو `off`). الافتراضي: `off`.
- `autoJoinAllowlist`: الغرف/الأسماء المستعارة المسموح بها عندما تكون `autoJoin` هي `allowlist`. تُحل إدخالات الأسماء المستعارة إلى معرّفات غرف أثناء معالجة الدعوات؛ ولا يثق OpenClaw في حالة الاسم المستعار التي تدعيها الغرفة المدعو إليها.
- `dm`: كتلة سياسة الرسائل المباشرة (`enabled` أو `policy` أو `allowFrom` أو `threadReplies`).
- يجب أن تكون إدخالات `dm.allowFrom` معرّفات مستخدم Matrix كاملة ما لم تكن قد قمت بحلها بالفعل عبر البحث الحي في الدليل.
- `dm.threadReplies`: تجاوز لسياسة السلاسل في الرسائل المباشرة فقط (`off` أو `inbound` أو `always`). ويتجاوز إعداد `threadReplies` الأعلى مستوى لكل من موضع الرد وعزل الجلسة في الرسائل المباشرة.
- `execApprovals`: تسليم موافقات exec الأصلية في Matrix (`enabled` أو `approvers` أو `target` أو `agentFilter` أو `sessionFilter`).
- `execApprovals.approvers`: معرّفات مستخدمي Matrix المسموح لهم بالموافقة على طلبات exec. وهو اختياري عندما تكون `dm.allowFrom` تحدد الموافقين بالفعل.
- `execApprovals.target`: `dm | channel | both` (الافتراضي: `dm`).
- `accounts`: تجاوزات مسماة لكل حساب. وتعمل القيم العليا في `channels.matrix` كقيم افتراضية لهذه الإدخالات.
- `groups`: خريطة سياسات لكل غرفة. فضّل معرّفات الغرف أو الأسماء المستعارة؛ ويتم تجاهل أسماء الغرف غير المحلولة في وقت التشغيل. تستخدم هوية الجلسة/المجموعة معرّف الغرفة الثابت بعد الحل، بينما تظل التسميات المقروءة للبشر مأخوذة من أسماء الغرف.
- `groups.<room>.account`: يقيّد إدخال غرفة موروثًا واحدًا إلى حساب Matrix محدد في الإعدادات متعددة الحسابات.
- `groups.<room>.allowBots`: تجاوز على مستوى الغرفة للمرسلين من البوتات المهيأة (`true` أو `"mentions"`).
- `groups.<room>.users`: قائمة سماح للمرسلين لكل غرفة.
- `groups.<room>.tools`: تجاوزات السماح/المنع للأدوات لكل غرفة.
- `groups.<room>.autoReply`: تجاوز على مستوى الغرفة لبوابة الإشارات. تؤدي `true` إلى تعطيل متطلبات الإشارة لتلك الغرفة؛ وتفرض `false` إعادتها.
- `groups.<room>.skills`: مرشح Skills اختياري على مستوى الغرفة.
- `groups.<room>.systemPrompt`: مقتطف system prompt اختياري على مستوى الغرفة.
- `rooms`: اسم مستعار قديم لـ `groups`.
- `actions`: بوابات الأدوات لكل إجراء (`messages` أو `reactions` أو `pins` أو `profile` أو `memberInfo` أو `channelInfo` أو `verification`).
## ذو صلة
- [Channels Overview](/channels) — جميع القنوات المدعومة
- [Pairing](/channels/pairing) — مصادقة الرسائل المباشرة وتدفق الاقتران
- [Groups](/channels/groups) — سلوك الدردشة الجماعية وبوابة الإشارات
- [Channel Routing](/channels/channel-routing) — توجيه الجلسات للرسائل
- [Security](/gateway/security) — نموذج الوصول والتقوية

479
docs/ar/channels/mattermost.md Normal file
View File

@ -0,0 +1,479 @@
---
read_when:
- إعداد Mattermost
- تصحيح أخطاء توجيه Mattermost
summary: إعداد بوت Mattermost وتكوين OpenClaw
title: Mattermost
x-i18n:
generated_at: "2026-04-05T12:36:18Z"
model: gpt-5.4
provider: openai
source_hash: f21dc7543176fda0b38b00fab60f0daae38dffcf68fa1cf7930a9f14ec57cb5a
source_path: channels/mattermost.md
workflow: 15
---
# Mattermost
الحالة: plugin مضمّن (رمز bot المميز + أحداث WebSocket). القنوات والمجموعات والرسائل الخاصة مدعومة.
Mattermost هو منصة مراسلة جماعية قابلة للاستضافة الذاتية؛ راجع الموقع الرسمي على
[mattermost.com](https://mattermost.com) للحصول على تفاصيل المنتج والتنزيلات.
## plugin المضمّن
يأتي Mattermost كـ plugin مضمّن في إصدارات OpenClaw الحالية، لذلك لا تحتاج
الإصدارات المعبأة العادية إلى تثبيت منفصل.
إذا كنت تستخدم إصدارًا أقدم أو تثبيتًا مخصصًا لا يتضمن Mattermost،
فثبّته يدويًا:
التثبيت عبر CLI ‏(سجل npm):
```bash
openclaw plugins install @openclaw/mattermost
```
نسخة محلية (عند التشغيل من مستودع git):
```bash
openclaw plugins install ./path/to/local/mattermost-plugin
```
التفاصيل: [Plugins](/tools/plugin)
## الإعداد السريع
1. تأكد من أن plugin Mattermost متاح.
- تتضمن إصدارات OpenClaw المعبأة الحالية هذا plugin بالفعل.
- يمكن للتثبيتات الأقدم/المخصصة إضافته يدويًا باستخدام الأوامر أعلاه.
2. أنشئ حساب bot في Mattermost وانسخ **رمز bot المميز**.
3. انسخ **عنوان URL الأساسي** لـ Mattermost (مثل `https://chat.example.com`).
4. قم بتكوين OpenClaw وابدأ gateway.
الحد الأدنى من التكوين:
```json5
{
channels: {
mattermost: {
enabled: true,
botToken: "mm-token",
baseUrl: "https://chat.example.com",
dmPolicy: "pairing",
},
},
}
```
## أوامر الشرطة المائلة الأصلية
أوامر الشرطة المائلة الأصلية اختيارية. عند تمكينها، يسجل OpenClaw أوامر الشرطة المائلة `oc_*` عبر
واجهة Mattermost API ويتلقى طلبات POST الراجعة على خادم HTTP الخاص بـ gateway.
```json5
{
channels: {
mattermost: {
commands: {
native: true,
nativeSkills: true,
callbackPath: "/api/channels/mattermost/command",
// استخدم هذا عندما لا يتمكن Mattermost من الوصول إلى gateway مباشرة (reverse proxy/عنوان URL عام).
callbackUrl: "https://gateway.example.com/api/channels/mattermost/command",
},
},
},
}
```
ملاحظات:
- تكون القيمة الافتراضية لـ `native: "auto"` هي التعطيل في Mattermost. عيّن `native: true` للتمكين.
- إذا تم حذف `callbackUrl`، فسيشتق OpenClaw قيمة من مضيف/منفذ gateway + `callbackPath`.
- في إعدادات الحسابات المتعددة، يمكن تعيين `commands` في المستوى الأعلى أو تحت
`channels.mattermost.accounts.<id>.commands` (تتجاوز قيم الحساب حقول المستوى الأعلى).
- يتم التحقق من عمليات callback الخاصة بالأوامر باستخدام الرموز المميزة لكل أمر التي يعيدها
Mattermost عندما يسجل OpenClaw أوامر `oc_*`.
- تفشل عمليات callback الخاصة بأوامر الشرطة المائلة بشكل مغلق عندما يفشل التسجيل، أو يكون بدء التشغيل جزئيًا، أو
لا يطابق رمز callback أحد الأوامر المسجلة.
- متطلب إمكانية الوصول: يجب أن تكون نقطة نهاية callback قابلة للوصول من خادم Mattermost.
- لا تعيّن `callbackUrl` إلى `localhost` إلا إذا كان Mattermost يعمل على نفس المضيف/namespace الشبكة مثل OpenClaw.
- لا تعيّن `callbackUrl` إلى عنوان URL الأساسي لـ Mattermost إلا إذا كان هذا العنوان يستخدم reverse-proxy للمسار `/api/channels/mattermost/command` إلى OpenClaw.
- فحص سريع هو `curl https://<gateway-host>/api/channels/mattermost/command`; يجب أن يعيد طلب GET قيمة `405 Method Not Allowed` من OpenClaw، وليس `404`.
- متطلب قائمة السماح لخروج Mattermost:
- إذا كان callback لديك يستهدف عناوين خاصة/tailnet/داخلية، فعيّن
`ServiceSettings.AllowedUntrustedInternalConnections` في Mattermost ليشمل مضيف/نطاق callback.
- استخدم إدخالات المضيف/النطاق، وليس عناوين URL كاملة.
- جيد: `gateway.tailnet-name.ts.net`
- سيئ: `https://gateway.tailnet-name.ts.net`
## متغيرات البيئة (الحساب الافتراضي)
اضبط هذه المتغيرات على مضيف gateway إذا كنت تفضل استخدام متغيرات البيئة:
- `MATTERMOST_BOT_TOKEN=...`
- `MATTERMOST_URL=https://chat.example.com`
تنطبق متغيرات البيئة فقط على الحساب **الافتراضي** (`default`). يجب أن تستخدم الحسابات الأخرى قيم التكوين.
## أوضاع الدردشة
يرد Mattermost على الرسائل الخاصة تلقائيًا. يتم التحكم في سلوك القنوات بواسطة `chatmode`:
- `oncall` (الافتراضي): الرد فقط عند الإشارة إليه بـ @ في القنوات.
- `onmessage`: الرد على كل رسالة في القناة.
- `onchar`: الرد عندما تبدأ الرسالة ببادئة تشغيل.
مثال على التكوين:
```json5
{
channels: {
mattermost: {
chatmode: "onchar",
oncharPrefixes: [">", "!"],
},
},
}
```
ملاحظات:
- ما زال `onchar` يرد على إشارات @ الصريحة.
- يتم احترام `channels.mattermost.requireMention` في التكوينات القديمة لكن `chatmode` هو المفضل.
## سلاسل الرسائل والجلسات
استخدم `channels.mattermost.replyToMode` للتحكم في ما إذا كانت الردود في القنوات والمجموعات تبقى في
القناة الرئيسية أو تبدأ سلسلة رسائل تحت المنشور المُشغِّل.
- `off` (الافتراضي): لا يتم الرد في سلسلة رسائل إلا عندما يكون المنشور الوارد داخل سلسلة بالفعل.
- `first`: بالنسبة لمنشورات القنوات/المجموعات ذات المستوى الأعلى، ابدأ سلسلة رسائل تحت ذلك المنشور ووجّه
المحادثة إلى جلسة ضمن نطاق السلسلة.
- `all`: نفس سلوك `first` في Mattermost حاليًا.
- تتجاهل الرسائل الخاصة هذا الإعداد وتبقى بدون سلاسل.
مثال على التكوين:
```json5
{
channels: {
mattermost: {
replyToMode: "all",
},
},
}
```
ملاحظات:
- تستخدم الجلسات ضمن نطاق السلسلة معرّف المنشور المُشغِّل كجذر للسلسلة.
- `first` و`all` متكافئان حاليًا لأنه بمجرد أن يملك Mattermost جذر سلسلة،
تستمر الأجزاء اللاحقة والوسائط في نفس السلسلة.
## التحكم في الوصول (الرسائل الخاصة)
- الافتراضي: `channels.mattermost.dmPolicy = "pairing"` ‏(يحصل المرسلون غير المعروفين على رمز اقتران).
- وافق عبر:
- `openclaw pairing list mattermost`
- `openclaw pairing approve mattermost <CODE>`
- الرسائل الخاصة العامة: `channels.mattermost.dmPolicy="open"` مع `channels.mattermost.allowFrom=["*"]`.
## القنوات (المجموعات)
- الافتراضي: `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"` ‏(مقيّد بالإشارة).
- ملاحظة وقت التشغيل: إذا كانت `channels.mattermost` مفقودة بالكامل، فإن وقت التشغيل يعود إلى `groupPolicy="allowlist"` لفحوصات المجموعات (حتى لو كانت `channels.defaults.groupPolicy` معيّنة).
مثال:
```json5
{
channels: {
mattermost: {
groupPolicy: "open",
groups: {
"*": { requireMention: true },
"team-channel-id": { requireMention: false },
},
},
},
}
```
## الأهداف للتسليم الصادر
استخدم صيغ الأهداف التالية مع `openclaw message send` أو cron/webhooks:
- `channel:<id>` لقناة
- `user:<id>` لرسالة خاصة
- `@username` لرسالة خاصة (يتم حلها عبر Mattermost API)
المعرّفات المعتمة المجردة (مثل `64ifufp...`) **ملتبسة** في Mattermost (معرّف مستخدم أم معرّف قناة).
يقوم OpenClaw بحلها **كمستخدم أولًا**:
- إذا كان المعرّف موجودًا كمستخدم (`GET /api/v4/users/<id>` ينجح)، يرسل OpenClaw **رسالة خاصة** عبر حل القناة المباشرة باستخدام `/api/v4/channels/direct`.
- بخلاف ذلك، يُعامل المعرّف على أنه **معرّف قناة**.
إذا كنت تحتاج إلى سلوك حتمي، فاستخدم دائمًا البوادئ الصريحة (`user:<id>` / `channel:<id>`).
## إعادة محاولة قناة الرسائل الخاصة
عندما يرسل OpenClaw إلى هدف رسالة خاصة في Mattermost ويحتاج إلى حل القناة المباشرة أولًا، فإنه
يعيد محاولة إخفاقات إنشاء القناة المباشرة العابرة افتراضيًا.
استخدم `channels.mattermost.dmChannelRetry` لضبط هذا السلوك عمومًا لـ plugin Mattermost،
أو `channels.mattermost.accounts.<id>.dmChannelRetry` لحساب واحد.
```json5
{
channels: {
mattermost: {
dmChannelRetry: {
maxRetries: 3,
initialDelayMs: 1000,
maxDelayMs: 10000,
timeoutMs: 30000,
},
},
},
}
```
ملاحظات:
- ينطبق هذا فقط على إنشاء قناة الرسائل الخاصة (`/api/v4/channels/direct`)، وليس على كل استدعاء Mattermost API.
- تنطبق إعادة المحاولات على الإخفاقات العابرة مثل حدود المعدل، واستجابات 5xx، وأخطاء الشبكة أو انتهاء المهلة.
- تُعامل أخطاء العميل 4xx بخلاف `429` على أنها دائمة ولا تتم إعادة محاولتها.
## التفاعلات (أداة الرسائل)
- استخدم `message action=react` مع `channel=mattermost`.
- `messageId` هو معرّف منشور Mattermost.
- تقبل `emoji` أسماء مثل `thumbsup` أو `:+1:` ‏(النقطتان اختيارية).
- عيّن `remove=true` ‏(منطقي) لإزالة تفاعل.
- يتم تمرير أحداث إضافة/إزالة التفاعل كأحداث نظام إلى جلسة الوكيل الموجّهة.
أمثلة:
```
message action=react channel=mattermost target=channel:<channelId> messageId=<postId> emoji=thumbsup
message action=react channel=mattermost target=channel:<channelId> messageId=<postId> emoji=thumbsup remove=true
```
التكوين:
- `channels.mattermost.actions.reactions`: تمكين/تعطيل إجراءات التفاعل (الافتراضي true).
- تجاوز لكل حساب: `channels.mattermost.accounts.<id>.actions.reactions`.
## الأزرار التفاعلية (أداة الرسائل)
أرسل رسائل تحتوي على أزرار قابلة للنقر. عندما ينقر المستخدم زرًا، يتلقى الوكيل
الاختيار ويمكنه الرد.
قم بتمكين الأزرار بإضافة `inlineButtons` إلى قدرات القناة:
```json5
{
channels: {
mattermost: {
capabilities: ["inlineButtons"],
},
},
}
```
استخدم `message action=send` مع معلمة `buttons`. الأزرار عبارة عن مصفوفة ثنائية الأبعاد (صفوف من الأزرار):
```
message action=send channel=mattermost target=channel:<channelId> buttons=[[{"text":"Yes","callback_data":"yes"},{"text":"No","callback_data":"no"}]]
```
حقول الزر:
- `text` (مطلوب): تسمية العرض.
- `callback_data` (مطلوب): القيمة التي تُرسل مرة أخرى عند النقر (تُستخدم كمعرّف الإجراء).
- `style` (اختياري): `"default"` أو `"primary"` أو `"danger"`.
عندما ينقر المستخدم زرًا:
1. تُستبدل كل الأزرار بسطر تأكيد (مثل "✓ **Yes** selected by @user").
2. يتلقى الوكيل الاختيار كرسالة واردة ويرد.
ملاحظات:
- تستخدم عمليات callback الخاصة بالأزرار تحقق HMAC-SHA256 ‏(تلقائي، ولا حاجة إلى تكوين).
- يزيل Mattermost بيانات callback من استجابات API الخاصة به (ميزة أمان)، لذلك تتم
إزالة جميع الأزرار عند النقر — ولا يمكن الإزالة الجزئية.
- يتم تنظيف معرّفات الإجراءات التي تحتوي على شرطات أو شرطات سفلية تلقائيًا
(بسبب قيد في توجيه Mattermost).
التكوين:
- `channels.mattermost.capabilities`: مصفوفة سلاسل للقدرات. أضف `"inlineButtons"` إلى
تمكين وصف أداة الأزرار في مطالبة نظام الوكيل.
- `channels.mattermost.interactions.callbackBaseUrl`: عنوان URL أساسي خارجي اختياري لعمليات callback
الخاصة بالأزرار (مثل `https://gateway.example.com`). استخدمه عندما يتعذر على Mattermost
الوصول إلى gateway عند مضيف الربط مباشرة.
- في إعدادات الحسابات المتعددة، يمكنك أيضًا تعيين الحقل نفسه تحت
`channels.mattermost.accounts.<id>.interactions.callbackBaseUrl`.
- إذا تم حذف `interactions.callbackBaseUrl`، يشتق OpenClaw عنوان URL الخاص بـ callback من
`gateway.customBindHost` + `gateway.port`، ثم يعود إلى `http://localhost:<port>`.
- قاعدة إمكانية الوصول: يجب أن يكون عنوان URL الخاص بـ callback للأزرار قابلاً للوصول من خادم Mattermost.
لا يعمل `localhost` إلا عندما يعمل Mattermost وOpenClaw على نفس المضيف/namespace الشبكة.
- إذا كان هدف callback لديك خاصًا/tailnet/داخليًا، فأضف مضيفه/نطاقه إلى
`ServiceSettings.AllowedUntrustedInternalConnections` في Mattermost.
### تكامل API مباشر (scripts خارجية)
يمكن لـ scripts وwebhooks الخارجية نشر الأزرار مباشرة عبر Mattermost REST API
بدلًا من المرور عبر أداة `message` الخاصة بالوكيل. استخدم `buildButtonAttachments()` من
الامتداد عندما يكون ذلك ممكنًا؛ وإذا كنت تنشر JSON خامًا، فاتبع هذه القواعد:
**بنية الحمولة:**
```json5
{
channel_id: "<channelId>",
message: "Choose an option:",
props: {
attachments: [
{
actions: [
{
id: "mybutton01", // أبجدي رقمي فقط — راجع أدناه
type: "button", // مطلوب، وإلا فسيتم تجاهل النقرات بصمت
name: "Approve", // تسمية العرض
style: "primary", // اختياري: "default" أو "primary" أو "danger"
integration: {
url: "https://gateway.example.com/mattermost/interactions/default",
context: {
action_id: "mybutton01", // يجب أن يطابق id الخاص بالزر (لاستخدامه في البحث عن الاسم)
action: "approve",
// ... أي حقول مخصصة ...
_token: "<hmac>", // راجع قسم HMAC أدناه
},
},
},
],
},
],
},
}
```
**القواعد الحرجة:**
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 من دونه.
**توليد رمز HMAC:**
يتحقق gateway من نقرات الأزرار باستخدام HMAC-SHA256. يجب على scripts الخارجية توليد رموز
تطابق منطق التحقق في gateway:
1. اشتق السر من رمز bot المميز:
`HMAC-SHA256(key="openclaw-mattermost-interactions", data=botToken)`
2. ابنِ كائن السياق بجميع الحقول **باستثناء** `_token`.
3. قم بالتسلسل باستخدام **مفاتيح مرتبة** و**من دون مسافات** (يستخدم gateway ‏`JSON.stringify`
مع مفاتيح مرتبة، ما ينتج خرجًا مضغوطًا).
4. وقّع: `HMAC-SHA256(key=secret, data=serializedContext)`
5. أضف الملخص السداسي الناتج كقيمة `_token` في السياق.
مثال Python:
```python
import hmac, hashlib, json
secret = hmac.new(
b"openclaw-mattermost-interactions",
bot_token.encode(), hashlib.sha256
).hexdigest()
ctx = {"action_id": "mybutton01", "action": "approve"}
payload = json.dumps(ctx, sort_keys=True, separators=(",", ":"))
token = hmac.new(secret.encode(), payload.encode(), hashlib.sha256).hexdigest()
context = {**ctx, "_token": token}
```
المشكلات الشائعة في HMAC:
- يضيف `json.dumps` في Python مسافات افتراضيًا (`{"key": "val"}`). استخدم
`separators=(",", ":")` لمطابقة الخرج المضغوط في JavaScript ‏(`{"key":"val"}`).
- وقّع دائمًا **كل** حقول السياق (باستثناء `_token`). يزيل gateway قيمة `_token` ثم
يوقّع كل ما تبقى. يؤدي توقيع مجموعة فرعية إلى فشل صامت في التحقق.
- استخدم `sort_keys=True` — يقوم gateway بترتيب المفاتيح قبل التوقيع، وقد يعيد Mattermost
ترتيب حقول السياق عند تخزين الحمولة.
- اشتق السر من رمز bot المميز (حتمي)، وليس من بايتات عشوائية. يجب أن يكون السر
نفسه في كل من العملية التي تنشئ الأزرار وgateway الذي يتحقق منها.
## مهايئ الدليل
يتضمن plugin Mattermost مهايئ دليل يحل أسماء القنوات والمستخدمين
عبر Mattermost API. يتيح هذا استخدام أهداف `#channel-name` و`@username` في
`openclaw message send` وعمليات التسليم عبر cron/webhook.
لا يلزم أي تكوين — يستخدم المهايئ رمز bot المميز من تكوين الحساب.
## حسابات متعددة
يدعم Mattermost حسابات متعددة تحت `channels.mattermost.accounts`:
```json5
{
channels: {
mattermost: {
accounts: {
default: { name: "Primary", botToken: "mm-token", baseUrl: "https://chat.example.com" },
alerts: { name: "Alerts", botToken: "mm-token-2", baseUrl: "https://alerts.example.com" },
},
},
},
}
```
## استكشاف الأخطاء وإصلاحها
- لا توجد ردود في القنوات: تأكد من وجود bot في القناة واذكره (oncall)، أو استخدم بادئة تشغيل (onchar)، أو عيّن `chatmode: "onmessage"`.
- أخطاء المصادقة: تحقق من رمز bot المميز وعنوان URL الأساسي وما إذا كان الحساب ممكّنًا.
- مشكلات الحسابات المتعددة: تنطبق متغيرات البيئة فقط على الحساب `default`.
- تعيد أوامر الشرطة المائلة الأصلية `Unauthorized: invalid command token.`: لم
يقبل OpenClaw رمز callback المميز. الأسباب المعتادة:
- فشل تسجيل أوامر الشرطة المائلة أو اكتمل جزئيًا فقط عند بدء التشغيل
- يصل callback إلى gateway/الحساب الخطأ
- ما زال Mattermost يملك أوامر قديمة تشير إلى هدف callback سابق
- أُعيد تشغيل 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/...`، فمن المحتمل أن يكون عنوان URL هذا قابلاً للوصول فقط عندما
يعمل Mattermost على نفس المضيف/namespace الشبكة مثل 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. تحقق من أنك توقّع كل حقول السياق (وليس مجموعة فرعية)، وتستخدم مفاتيح مرتبة، وJSON مضغوطًا (من دون مسافات). راجع قسم HMAC أعلاه.
- تُظهر سجلات gateway الرسالة `missing _token in context`: الحقل `_token` غير موجود في سياق الزر. تأكد من تضمينه عند إنشاء حمولة التكامل.
- يُظهر التأكيد معرّفًا خامًا بدلًا من اسم الزر: `context.action_id` لا يطابق `id` الخاص بالزر. عيّن الاثنين إلى القيمة المنظفة نفسها.
- الوكيل لا يعرف الأزرار: أضف `capabilities: ["inlineButtons"]` إلى تكوين قناة Mattermost.
## ذو صلة
- [نظرة عامة على القنوات](/channels) — جميع القنوات المدعومة
- [الاقتران](/channels/pairing) — مصادقة الرسائل الخاصة وتدفق الاقتران
- [المجموعات](/channels/groups) — سلوك الدردشة الجماعية وضبط الإشارات
- [توجيه القنوات](/channels/channel-routing) — توجيه الجلسات للرسائل
- [الأمان](/gateway/security) — نموذج الوصول والتقوية

812
docs/ar/channels/msteams.md Normal file
View File

@ -0,0 +1,812 @@
---
read_when:
- العمل على ميزات قناة Microsoft Teams
summary: حالة دعم بوت Microsoft Teams وإمكاناته وإعداده
title: Microsoft Teams
x-i18n:
generated_at: "2026-04-05T12:37:11Z"
model: gpt-5.4
provider: openai
source_hash: 99fc6e136893ec65dc85d3bc0c0d92134069a2f3b8cb4fcf66c14674399b3eaf
source_path: channels/msteams.md
workflow: 15
---
# Microsoft Teams
> "اتركوا كل أمل، يا من تدخلون هنا."
تم التحديث: 2026-01-21
الحالة: النص + مرفقات الرسائل المباشرة مدعومان؛ ويتطلب إرسال الملفات في القنوات/المجموعات `sharePointSiteId` + أذونات Graph (راجع [إرسال الملفات في الدردشات الجماعية](#sending-files-in-group-chats)). تُرسل الاستطلاعات عبر Adaptive Cards. وتعرض إجراءات الرسائل الإجراء الصريح `upload-file` لعمليات الإرسال التي تبدأ بالملف.
## المكون الإضافي المضمّن
يأتي Microsoft Teams كمكون إضافي مضمّن في إصدارات OpenClaw الحالية، لذلك لا يلزم
أي تثبيت منفصل في البنية المعبأة العادية.
إذا كنت تستخدم إصدارًا أقدم أو تثبيتًا مخصصًا يستبعد Teams المضمّن،
فقم بتثبيته يدويًا:
```bash
openclaw plugins install @openclaw/msteams
```
نسخة checkout محلية (عند التشغيل من مستودع git):
```bash
openclaw plugins install ./path/to/local/msteams-plugin
```
التفاصيل: [Plugins](/tools/plugin)
## إعداد سريع (للمبتدئين)
1. تأكد من أن المكون الإضافي لـ Microsoft Teams متاح.
- إصدارات OpenClaw المعبأة الحالية تتضمنه بالفعل.
- يمكن للإصدارات/التثبيتات الأقدم أو المخصصة إضافته يدويًا بالأوامر أعلاه.
2. أنشئ **Azure Bot** ‏(App ID + client secret + tenant ID).
3. اضبط OpenClaw باستخدام بيانات الاعتماد هذه.
4. اكشف `/api/messages` ‏(المنفذ 3978 افتراضيًا) عبر URL عام أو نفق.
5. ثبّت حزمة تطبيق Teams وابدأ gateway.
الحد الأدنى من الإعداد:
```json5
{
channels: {
msteams: {
enabled: true,
appId: "<APP_ID>",
appPassword: "<APP_PASSWORD>",
tenantId: "<TENANT_ID>",
webhook: { port: 3978, path: "/api/messages" },
},
},
}
```
ملاحظة: تُحظر الدردشات الجماعية افتراضيًا (`channels.msteams.groupPolicy: "allowlist"`). للسماح بالردود في المجموعات، اضبط `channels.msteams.groupAllowFrom` (أو استخدم `groupPolicy: "open"` للسماح لأي عضو، مع تقييد الإشارات).
## الأهداف
- التحدث إلى OpenClaw عبر الرسائل المباشرة في Teams أو الدردشات الجماعية أو القنوات.
- إبقاء التوجيه حتميًا: تعود الردود دائمًا إلى القناة التي وصلت منها.
- الاعتماد افتراضيًا على سلوك آمن للقناة (الإشارات مطلوبة ما لم يتم تكوين خلاف ذلك).
## عمليات كتابة الإعداد
يُسمح افتراضيًا لـ Microsoft Teams بكتابة تحديثات الإعداد الناتجة عن `/config set|unset` (يتطلب `commands.config: true`).
عطّل ذلك باستخدام:
```json5
{
channels: { msteams: { configWrites: false } },
}
```
## التحكم في الوصول (الرسائل المباشرة + المجموعات)
**الوصول عبر الرسائل المباشرة**
- الافتراضي: `channels.msteams.dmPolicy = "pairing"`. يتم تجاهل المرسلين غير المعروفين حتى تتم الموافقة عليهم.
- يجب أن يستخدم `channels.msteams.allowFrom` معرّفات كائنات AAD الثابتة.
- أسماء UPN/العرض قابلة للتغيير؛ والمطابقة المباشرة معطلة افتراضيًا ولا تُفعّل إلا باستخدام `channels.msteams.dangerouslyAllowNameMatching: true`.
- يمكن للمعالج تحويل الأسماء إلى معرّفات عبر Microsoft Graph عندما تسمح بيانات الاعتماد بذلك.
**الوصول إلى المجموعات**
- الافتراضي: `channels.msteams.groupPolicy = "allowlist"` (محظور ما لم تضف `groupAllowFrom`). استخدم `channels.defaults.groupPolicy` لتجاوز القيمة الافتراضية عند عدم ضبطها.
- يتحكم `channels.msteams.groupAllowFrom` في المرسلين الذين يمكنهم التشغيل في الدردشات/القنوات الجماعية (ويعود إلى `channels.msteams.allowFrom` عند الحاجة).
- اضبط `groupPolicy: "open"` للسماح لأي عضو (مع بقاء تقييد الإشارات افتراضيًا).
- لعدم السماح **بأي قنوات**، اضبط `channels.msteams.groupPolicy: "disabled"`.
مثال:
```json5
{
channels: {
msteams: {
groupPolicy: "allowlist",
groupAllowFrom: ["user@org.com"],
},
},
}
```
**Teams + قائمة سماح القنوات**
- حدّد نطاق الردود في المجموعات/القنوات عبر إدراج الفرق والقنوات ضمن `channels.msteams.teams`.
- يجب أن تستخدم المفاتيح معرّفات الفرق الثابتة ومعرّفات محادثات القنوات.
- عندما يكون `groupPolicy="allowlist"` وتوجد قائمة سماح للفرق، لا تُقبل إلا الفرق/القنوات المُدرجة (مع تقييد الإشارات).
- يقبل معالج الإعداد إدخالات `Team/Channel` ويخزنها لك.
- عند بدء التشغيل، يحل OpenClaw أسماء الفرق/القنوات وأسماء المستخدمين في قوائم السماح إلى معرّفات (عندما تسمح أذونات Graph بذلك)
ويسجل هذا الربط؛ وتُحتفظ بأسماء الفرق/القنوات غير المحلولة كما أُدخلت ولكن يتم تجاهلها للتوجيه افتراضيًا ما لم يكن `channels.msteams.dangerouslyAllowNameMatching: true` مفعّلًا.
مثال:
```json5
{
channels: {
msteams: {
groupPolicy: "allowlist",
teams: {
"My Team": {
channels: {
General: { requireMention: true },
},
},
},
},
},
}
```
## كيف يعمل
1. تأكد من أن المكون الإضافي لـ Microsoft Teams متاح.
- إصدارات OpenClaw المعبأة الحالية تتضمنه بالفعل.
- يمكن للإصدارات/التثبيتات الأقدم أو المخصصة إضافته يدويًا بالأوامر أعلاه.
2. أنشئ **Azure Bot** ‏(App ID + secret + tenant ID).
3. أنشئ **حزمة تطبيق Teams** تشير إلى البوت وتتضمن أذونات RSC أدناه.
4. ارفع/ثبّت تطبيق Teams داخل فريق (أو نطاق شخصي للرسائل المباشرة).
5. اضبط `msteams` في `~/.openclaw/openclaw.json` (أو متغيرات البيئة) وابدأ gateway.
6. يستمع gateway إلى حركة webhook الخاصة بـ Bot Framework على `/api/messages` افتراضيًا.
## إعداد Azure Bot (المتطلبات المسبقة)
قبل إعداد OpenClaw، تحتاج إلى إنشاء مورد Azure Bot.
### الخطوة 1: إنشاء Azure Bot
1. انتقل إلى [Create Azure Bot](https://portal.azure.com/#create/Microsoft.AzureBot)
2. املأ علامة التبويب **Basics**:
| الحقل | القيمة |
| ------------------ | --------------------------------------------------------- |
| **Bot handle** | اسم البوت الخاص بك، مثل `openclaw-msteams` (يجب أن يكون فريدًا) |
| **Subscription** | اختر اشتراك Azure الخاص بك |
| **Resource group** | أنشئ مجموعة جديدة أو استخدم مجموعة موجودة |
| **Pricing tier** | **Free** للتطوير/الاختبار |
| **Type of App** | **Single Tenant** (موصى به - راجع الملاحظة أدناه) |
| **Creation type** | **Create new Microsoft App ID** |
> **إشعار إيقاف:** تم إيقاف إنشاء البوتات الجديدة متعددة المستأجرين بعد 2025-07-31. استخدم **Single Tenant** للبوتات الجديدة.
3. انقر **Review + create** → **Create** (انتظر نحو دقيقة إلى دقيقتين)
### الخطوة 2: الحصول على بيانات الاعتماد
1. انتقل إلى مورد Azure Bot الخاص بك → **Configuration**
2. انسخ **Microsoft App ID** → هذا هو `appId` الخاص بك
3. انقر **Manage Password** → انتقل إلى App Registration
4. ضمن **Certificates & secrets** → **New client secret** → انسخ **Value** → هذا هو `appPassword` الخاص بك
5. انتقل إلى **Overview** → انسخ **Directory (tenant) ID** → هذا هو `tenantId` الخاص بك
### الخطوة 3: إعداد نقطة نهاية المراسلة
1. في Azure Bot → **Configuration**
2. اضبط **Messaging endpoint** على webhook URL الخاص بك:
- الإنتاج: `https://your-domain.com/api/messages`
- التطوير المحلي: استخدم نفقًا (راجع [التطوير المحلي](#local-development-tunneling) أدناه)
### الخطوة 4: تفعيل قناة Teams
1. في Azure Bot → **Channels**
2. انقر **Microsoft Teams** → Configure → Save
3. اقبل شروط الخدمة
## التطوير المحلي (الأنفاق)
لا يستطيع Teams الوصول إلى `localhost`. استخدم نفقًا للتطوير المحلي:
**الخيار A: ngrok**
```bash
ngrok http 3978
# انسخ URL الذي يبدأ بـ https، مثل https://abc123.ngrok.io
# اضبط نقطة نهاية المراسلة على: https://abc123.ngrok.io/api/messages
```
**الخيار B: Tailscale Funnel**
```bash
tailscale funnel 3978
# استخدم URL الخاص بـ Tailscale funnel كنقطة نهاية للمراسلة
```
## Teams Developer Portal (بديل)
بدلًا من إنشاء manifest ZIP يدويًا، يمكنك استخدام [Teams Developer Portal](https://dev.teams.microsoft.com/apps):
1. انقر **+ New app**
2. املأ المعلومات الأساسية (الاسم، الوصف، معلومات المطور)
3. انتقل إلى **App features** → **Bot**
4. اختر **Enter a bot ID manually** والصق Azure Bot App ID
5. فعّل النطاقات: **Personal** و**Team** و**Group Chat**
6. انقر **Distribute** → **Download app package**
7. في Teams: **Apps** → **Manage your apps** → **Upload a custom app** → اختر ملف ZIP
غالبًا ما يكون هذا أسهل من تعديل ملفات manifest JSON يدويًا.
## اختبار البوت
**الخيار A: Azure Web Chat (تحقق من webhook أولًا)**
1. في Azure Portal → مورد Azure Bot الخاص بك → **Test in Web Chat**
2. أرسل رسالة - يجب أن ترى ردًا
3. وهذا يؤكد أن نقطة نهاية webhook تعمل قبل إعداد Teams
**الخيار B: Teams (بعد تثبيت التطبيق)**
1. ثبّت تطبيق Teams (تحميل جانبي أو كتالوج المؤسسة)
2. اعثر على البوت في Teams وأرسل رسالة مباشرة
3. تحقق من سجلات gateway لرؤية النشاط الوارد
## الإعداد (الحد الأدنى للنص فقط)
1. **تأكد من أن المكون الإضافي لـ Microsoft Teams متاح**
- إصدارات OpenClaw المعبأة الحالية تتضمنه بالفعل.
- يمكن للإصدارات/التثبيتات الأقدم أو المخصصة إضافته يدويًا:
- من npm: `openclaw plugins install @openclaw/msteams`
- من نسخة checkout محلية: `openclaw plugins install ./path/to/local/msteams-plugin`
2. **تسجيل البوت**
- أنشئ Azure Bot (راجع أعلاه) ودوّن:
- App ID
- Client secret ‏(App password)
- Tenant ID ‏(single-tenant)
3. **manifest تطبيق Teams**
- أضف إدخال `bot` حيث `botId = <App ID>`.
- النطاقات: `personal`, `team`, `groupChat`.
- `supportsFiles: true` ‏(مطلوب لمعالجة الملفات في النطاق الشخصي).
- أضف أذونات RSC (أدناه).
- أنشئ الأيقونات: `outline.png` ‏(32x32) و`color.png` ‏(192x192).
- اضغط الملفات الثلاثة معًا في zip: ‏`manifest.json`, `outline.png`, `color.png`.
4. **اضبط OpenClaw**
```json5
{
channels: {
msteams: {
enabled: true,
appId: "<APP_ID>",
appPassword: "<APP_PASSWORD>",
tenantId: "<TENANT_ID>",
webhook: { port: 3978, path: "/api/messages" },
},
},
}
```
يمكنك أيضًا استخدام متغيرات البيئة بدلًا من مفاتيح الإعداد:
- `MSTEAMS_APP_ID`
- `MSTEAMS_APP_PASSWORD`
- `MSTEAMS_TENANT_ID`
5. **نقطة نهاية البوت**
- اضبط Azure Bot Messaging Endpoint على:
- `https://<host>:3978/api/messages` ‏(أو المسار/المنفذ الذي اخترته).
6. **شغّل gateway**
- تبدأ قناة Teams تلقائيًا عندما يكون المكون الإضافي المضمّن أو المثبّت يدويًا متاحًا وتوجد إعدادات `msteams` مع بيانات الاعتماد.
## إجراء معلومات العضو
يعرض OpenClaw إجراء `member-info` مدعومًا من Graph لـ Microsoft Teams حتى تتمكن الوكلاء وعمليات الأتمتة من حل تفاصيل أعضاء القناة (اسم العرض والبريد الإلكتروني والدور) مباشرةً من Microsoft Graph.
المتطلبات:
- إذن RSC ‏`Member.Read.Group` (موجود بالفعل في manifest الموصى به)
- لعمليات البحث عبر الفرق: إذن تطبيق Graph ‏`User.Read.All` مع موافقة المسؤول
يخضع الإجراء لـ `channels.msteams.actions.memberInfo` (الافتراضي: مفعّل عند توفر بيانات اعتماد Graph).
## سياق السجل
- يتحكم `channels.msteams.historyLimit` في عدد رسائل القناة/المجموعة الأخيرة التي تُغلَّف داخل الموجّه.
- يعود إلى `messages.groupChat.historyLimit`. اضبطه إلى `0` للتعطيل (الافتراضي 50).
- يُرشّح سجل السلسلة الذي يتم جلبه بواسطة قوائم سماح المرسلين (`allowFrom` / `groupAllowFrom`)، لذا فإن تهيئة سياق السلسلة تتضمن فقط الرسائل من المرسلين المسموح لهم.
- يتم تمرير سياق المرفقات المقتبسة (`ReplyTo*` المشتق من HTML الرد في Teams) حاليًا كما تم استلامه.
- بمعنى آخر، تتحكم قوائم السماح في من يمكنه تشغيل الوكيل؛ ولا تُرشّح اليوم إلا بعض مسارات السياق التكميلي المحددة.
- يمكن تقييد سجل الرسائل المباشرة عبر `channels.msteams.dmHistoryLimit` (أدوار المستخدم). والتجاوزات لكل مستخدم: `channels.msteams.dms["<user_id>"].historyLimit`.
## أذونات Teams RSC الحالية (Manifest)
هذه هي أذونات **resourceSpecific** الحالية في manifest تطبيق Teams لدينا. وهي لا تنطبق إلا داخل الفريق/الدردشة التي ثُبّت فيها التطبيق.
**للقنوات (نطاق الفريق):**
- `ChannelMessage.Read.Group` ‏(Application) - تلقي جميع رسائل القناة بدون @mention
- `ChannelMessage.Send.Group` ‏(Application)
- `Member.Read.Group` ‏(Application)
- `Owner.Read.Group` ‏(Application)
- `ChannelSettings.Read.Group` ‏(Application)
- `TeamMember.Read.Group` ‏(Application)
- `TeamSettings.Read.Group` ‏(Application)
**للدردشات الجماعية:**
- `ChatMessage.Read.Chat` ‏(Application) - تلقي جميع رسائل الدردشة الجماعية بدون @mention
## مثال على Teams Manifest (منقّح)
مثال أدنى صالح مع الحقول المطلوبة. استبدل المعرّفات وعناوين URL.
```json5
{
$schema: "https://developer.microsoft.com/en-us/json-schemas/teams/v1.23/MicrosoftTeams.schema.json",
manifestVersion: "1.23",
version: "1.0.0",
id: "00000000-0000-0000-0000-000000000000",
name: { short: "OpenClaw" },
developer: {
name: "Your Org",
websiteUrl: "https://example.com",
privacyUrl: "https://example.com/privacy",
termsOfUseUrl: "https://example.com/terms",
},
description: { short: "OpenClaw in Teams", full: "OpenClaw in Teams" },
icons: { outline: "outline.png", color: "color.png" },
accentColor: "#5B6DEF",
bots: [
{
botId: "11111111-1111-1111-1111-111111111111",
scopes: ["personal", "team", "groupChat"],
isNotificationOnly: false,
supportsCalling: false,
supportsVideo: false,
supportsFiles: true,
},
],
webApplicationInfo: {
id: "11111111-1111-1111-1111-111111111111",
},
authorization: {
permissions: {
resourceSpecific: [
{ name: "ChannelMessage.Read.Group", type: "Application" },
{ name: "ChannelMessage.Send.Group", type: "Application" },
{ name: "Member.Read.Group", type: "Application" },
{ name: "Owner.Read.Group", type: "Application" },
{ name: "ChannelSettings.Read.Group", type: "Application" },
{ name: "TeamMember.Read.Group", type: "Application" },
{ name: "TeamSettings.Read.Group", type: "Application" },
{ name: "ChatMessage.Read.Chat", type: "Application" },
],
},
},
}
```
### ملاحظات manifest المهمة (حقول لا غنى عنها)
- يجب أن يطابق `bots[].botId` **تمامًا** Azure Bot App ID.
- يجب أن يطابق `webApplicationInfo.id` **تمامًا** Azure Bot App ID.
- يجب أن يتضمن `bots[].scopes` الأسطح التي تخطط لاستخدامها (`personal`, `team`, `groupChat`).
- يتطلب `bots[].supportsFiles: true` لمعالجة الملفات في النطاق الشخصي.
- يجب أن يتضمن `authorization.permissions.resourceSpecific` أذونات قراءة/إرسال القنوات إذا كنت تريد حركة مرور القنوات.
### تحديث تطبيق موجود
لتحديث تطبيق Teams مثبّت بالفعل (مثلًا لإضافة أذونات RSC):
1. حدّث `manifest.json` بالإعدادات الجديدة
2. **زد الحقل `version`** ‏(مثلًا `1.0.0` → `1.1.0`)
3. **أعد ضغط** manifest مع الأيقونات (`manifest.json`, `outline.png`, `color.png`)
4. ارفع ملف zip الجديد:
- **الخيار A (Teams Admin Center):** Teams Admin Center → Teams apps → Manage apps → اعثر على تطبيقك → Upload new version
- **الخيار B (Sideload):** في Teams → Apps → Manage your apps → Upload a custom app
5. **لقنوات الفرق:** أعد تثبيت التطبيق في كل فريق حتى تدخل الأذونات الجديدة حيز التنفيذ
6. **أغلق Teams تمامًا ثم أعد تشغيله** (وليس مجرد إغلاق النافذة) لمسح بيانات تعريف التطبيق المخزنة مؤقتًا
## الإمكانات: RSC فقط مقابل Graph
### مع **Teams RSC فقط** (التطبيق مثبت، من دون أذونات Microsoft Graph API)
يعمل:
- قراءة محتوى **النص** لرسائل القنوات.
- إرسال محتوى **نص** رسائل القنوات.
- استقبال مرفقات الملفات في **النطاق الشخصي (DM)**.
لا يعمل:
- **الصور أو محتويات الملفات** في القنوات/المجموعات (تتضمن الحمولة مجرد HTML stub).
- تنزيل المرفقات المخزنة في SharePoint/OneDrive.
- قراءة سجل الرسائل (فيما يتجاوز حدث webhook المباشر).
### مع **Teams RSC + أذونات تطبيق Microsoft Graph**
يضيف:
- تنزيل المحتويات المستضافة (الصور الملصقة داخل الرسائل).
- تنزيل مرفقات الملفات المخزنة في SharePoint/OneDrive.
- قراءة سجل رسائل القنوات/الدردشات عبر Graph.
### RSC مقابل Graph API
| الإمكانية | أذونات RSC | Graph API |
| ----------------------- | --------------------- | ------------------------------------ |
| **الرسائل الآنية** | نعم (عبر webhook) | لا (استطلاع فقط) |
| **الرسائل التاريخية** | لا | نعم (يمكن الاستعلام عن السجل) |
| **تعقيد الإعداد** | manifest التطبيق فقط | يتطلب موافقة المسؤول + تدفق token |
| **يعمل دون اتصال** | لا (يجب أن يكون قيد التشغيل) | نعم (يمكن الاستعلام في أي وقت) |
**الخلاصة:** يستخدم RSC للاستماع الآني؛ ويُستخدم Graph API للوصول إلى السجل التاريخي. وللحاق بالرسائل الفائتة أثناء عدم الاتصال، تحتاج إلى Graph API مع `ChannelMessage.Read.All` ‏(يتطلب موافقة المسؤول).
## الوسائط + السجل المفعّلان عبر Graph (مطلوبان للقنوات)
إذا كنت تحتاج إلى الصور/الملفات في **القنوات** أو تريد جلب **سجل الرسائل**، فيجب تفعيل أذونات Microsoft Graph ومنح موافقة المسؤول.
1. في Entra ID ‏(Azure AD) **App Registration**، أضف أذونات **Application** لـ Microsoft Graph:
- `ChannelMessage.Read.All` ‏(مرفقات القنوات + السجل)
- `Chat.Read.All` أو `ChatMessage.Read.All` ‏(للدردشات الجماعية)
2. **امنح موافقة المسؤول** للمستأجر.
3. زِد **إصدار manifest** لتطبيق Teams، وأعد رفعه، و**أعد تثبيت التطبيق في Teams**.
4. **أغلق Teams تمامًا ثم أعد تشغيله** لمسح بيانات تعريف التطبيق المخزنة مؤقتًا.
**إذن إضافي لإشارات المستخدمين:** تعمل إشارات @ للمستخدمين مباشرةً للمستخدمين الموجودين في المحادثة. ولكن إذا أردت البحث ديناميكيًا عن مستخدمين والإشارة إليهم وهم **ليسوا في المحادثة الحالية**، فأضف إذن `User.Read.All` ‏(Application) وامنح موافقة المسؤول.
## القيود المعروفة
### مهلات webhook
يسلّم Teams الرسائل عبر HTTP webhook. وإذا استغرقت المعالجة وقتًا طويلًا جدًا (مثل بطء استجابات LLM)، فقد ترى:
- مهلات gateway
- إعادة Teams محاولة إرسال الرسالة (مما يسبب التكرار)
- إسقاط الردود
يتعامل OpenClaw مع ذلك عبر إعادة الاستجابة بسرعة وإرسال الردود بشكل استباقي، ولكن قد تستمر المشكلات مع الاستجابات البطيئة جدًا.
### التنسيق
Markdown في Teams أكثر محدودية من Slack أو Discord:
- يعمل التنسيق الأساسي: **غامق** و_مائل_ و`code` والروابط
- قد لا تُعرض Markdown المعقدة (الجداول والقوائم المتداخلة) بشكل صحيح
- تُدعم Adaptive Cards للاستطلاعات وإرسال البطاقات العامة (راجع أدناه)
## الإعداد
الإعدادات الأساسية (راجع `/gateway/configuration` لأنماط القنوات المشتركة):
- `channels.msteams.enabled`: تفعيل/تعطيل القناة.
- `channels.msteams.appId`, `channels.msteams.appPassword`, `channels.msteams.tenantId`: بيانات اعتماد البوت.
- `channels.msteams.webhook.port` ‏(الافتراضي `3978`)
- `channels.msteams.webhook.path` ‏(الافتراضي `/api/messages`)
- `channels.msteams.dmPolicy`: ‏`pairing | allowlist | open | disabled` ‏(الافتراضي: pairing)
- `channels.msteams.allowFrom`: قائمة السماح للرسائل المباشرة (يوصى بمعرّفات كائنات AAD). يحل المعالج الأسماء إلى معرّفات أثناء الإعداد عندما يكون وصول Graph متاحًا.
- `channels.msteams.dangerouslyAllowNameMatching`: مفتاح طوارئ لإعادة تفعيل مطابقة UPN/أسماء العرض القابلة للتغيير والتوجيه المباشر بأسماء الفرق/القنوات.
- `channels.msteams.textChunkLimit`: حجم تقسيم النص الصادر.
- `channels.msteams.chunkMode`: ‏`length` ‏(الافتراضي) أو `newline` للتقسيم على الأسطر الفارغة (حدود الفقرات) قبل التقسيم حسب الطول.
- `channels.msteams.mediaAllowHosts`: قائمة السماح لمضيفي المرفقات الواردة (الافتراضي نطاقات Microsoft/Teams).
- `channels.msteams.mediaAuthAllowHosts`: قائمة السماح لإرفاق رؤوس Authorization عند إعادة محاولة الوسائط (الافتراضي مضيفو Graph + Bot Framework).
- `channels.msteams.requireMention`: طلب @mention في القنوات/المجموعات (الافتراضي true).
- `channels.msteams.replyStyle`: ‏`thread | top-level` ‏(راجع [نمط الرد](#reply-style-threads-vs-posts)).
- `channels.msteams.teams.<teamId>.replyStyle`: تجاوز لكل فريق.
- `channels.msteams.teams.<teamId>.requireMention`: تجاوز لكل فريق.
- `channels.msteams.teams.<teamId>.tools`: تجاوزات سياسة الأدوات الافتراضية لكل فريق (`allow`/`deny`/`alsoAllow`) تُستخدم عندما يكون تجاوز القناة مفقودًا.
- `channels.msteams.teams.<teamId>.toolsBySender`: تجاوزات سياسة الأدوات الافتراضية لكل فريق ولكل مرسل (الرمز الشامل `"*"` مدعوم).
- `channels.msteams.teams.<teamId>.channels.<conversationId>.replyStyle`: تجاوز لكل قناة.
- `channels.msteams.teams.<teamId>.channels.<conversationId>.requireMention`: تجاوز لكل قناة.
- `channels.msteams.teams.<teamId>.channels.<conversationId>.tools`: تجاوزات سياسة الأدوات لكل قناة (`allow`/`deny`/`alsoAllow`).
- `channels.msteams.teams.<teamId>.channels.<conversationId>.toolsBySender`: تجاوزات سياسة الأدوات لكل قناة ولكل مرسل (الرمز الشامل `"*"` مدعوم).
- يجب أن تستخدم مفاتيح `toolsBySender` بادئات صريحة:
`id:`, `e164:`, `username:`, `name:` (أما المفاتيح القديمة غير المسبوقة فما تزال تُطابق `id:` فقط).
- `channels.msteams.actions.memberInfo`: تفعيل أو تعطيل إجراء معلومات العضو المدعوم من Graph (الافتراضي: مفعّل عند توفر بيانات اعتماد Graph).
- `channels.msteams.sharePointSiteId`: معرّف موقع SharePoint لرفع الملفات في الدردشات/القنوات الجماعية (راجع [إرسال الملفات في الدردشات الجماعية](#sending-files-in-group-chats)).
## التوجيه والجلسات
- تتبع مفاتيح الجلسات صيغة الوكيل القياسية (راجع [/concepts/session](/concepts/session)):
- تشترك الرسائل المباشرة في الجلسة الرئيسية (`agent:<agentId>:<mainKey>`).
- تستخدم رسائل القنوات/المجموعات معرّف المحادثة:
- `agent:<agentId>:msteams:channel:<conversationId>`
- `agent:<agentId>:msteams:group:<conversationId>`
## نمط الرد: Threads مقابل Posts
قدّم Teams مؤخرًا نمطي واجهة مستخدم للقنوات فوق نموذج البيانات الأساسي نفسه:
| النمط | الوصف | `replyStyle` الموصى به |
| ------------------------ | -------------------------------------------------------- | ---------------------- |
| **Posts** ‏(الكلاسيكي) | تظهر الرسائل كبطاقات مع ردود مترابطة تحتها | `thread` ‏(الافتراضي) |
| **Threads** ‏(على نمط Slack) | تتدفق الرسائل خطيًا، بشكل أقرب إلى Slack | `top-level` |
**المشكلة:** لا تعرض Teams API نمط واجهة المستخدم الذي تستخدمه القناة. إذا استخدمت `replyStyle` خاطئًا:
- `thread` في قناة بنمط Threads → تظهر الردود متداخلة بشكل غير ملائم
- `top-level` في قناة بنمط Posts → تظهر الردود كمنشورات مستقلة على المستوى الأعلى بدلًا من أن تكون داخل السلسلة
**الحل:** اضبط `replyStyle` لكل قناة بحسب إعداد القناة:
```json5
{
channels: {
msteams: {
replyStyle: "thread",
teams: {
"19:abc...@thread.tacv2": {
channels: {
"19:xyz...@thread.tacv2": {
replyStyle: "top-level",
},
},
},
},
},
},
}
```
## المرفقات والصور
**القيود الحالية:**
- **الرسائل المباشرة:** تعمل الصور ومرفقات الملفات عبر Teams bot file APIs.
- **القنوات/المجموعات:** تعيش المرفقات في تخزين M365 ‏(SharePoint/OneDrive). لا تتضمن حمولة webhook إلا HTML stub، وليس بايتات الملف الفعلية. **أذونات Graph API مطلوبة** لتنزيل مرفقات القنوات.
- لعمليات الإرسال الصريحة التي تبدأ بالملف، استخدم `action=upload-file` مع `media` / `filePath` / `path`؛ وتصبح `message` الاختيارية هي النص/التعليق المصاحب، بينما يتجاوز `filename` الاسم المرفوع.
من دون أذونات Graph، ستُستقبل رسائل القنوات التي تحتوي على صور كنص فقط (ولا يمكن للبوت الوصول إلى محتوى الصورة).
وبشكل افتراضي، ينزّل OpenClaw الوسائط فقط من أسماء مضيفي Microsoft/Teams. ويمكنك تجاوز ذلك عبر `channels.msteams.mediaAllowHosts` ‏(استخدم `["*"]` للسماح بأي مضيف).
ولا تُرفق رؤوس Authorization إلا للمضيفين المدرجين في `channels.msteams.mediaAuthAllowHosts` ‏(الافتراضي مضيفو Graph + Bot Framework). أبقِ هذه القائمة صارمة (وتجنب اللواحق متعددة المستأجرين).
## إرسال الملفات في الدردشات الجماعية
يمكن للبوتات إرسال الملفات في الرسائل المباشرة باستخدام تدفق FileConsentCard ‏(مدمج). لكن **إرسال الملفات في الدردشات/القنوات الجماعية** يتطلب إعدادًا إضافيًا:
| السياق | كيفية إرسال الملفات | الإعداد المطلوب |
| ------------------------ | ----------------------------------------- | ----------------------------------------------- |
| **الرسائل المباشرة** | FileConsentCard → يقبل المستخدم → يرفع البوت | يعمل مباشرةً |
| **الدردشات/القنوات الجماعية** | رفع إلى SharePoint → رابط مشاركة | يتطلب `sharePointSiteId` + أذونات Graph |
| **الصور (أي سياق)** | مضمنة داخل الرسالة بترميز Base64 | تعمل مباشرةً |
### لماذا تحتاج الدردشات الجماعية إلى SharePoint
لا تمتلك البوتات محرك OneDrive شخصيًا (ونقطة نهاية Graph API ‏`/me/drive` لا تعمل لهويات التطبيقات). ولإرسال الملفات في الدردشات/القنوات الجماعية، يرفع البوت الملف إلى **موقع SharePoint** وينشئ رابط مشاركة.
### الإعداد
1. **أضف أذونات Graph API** في Entra ID ‏(Azure AD) → App Registration:
- `Sites.ReadWrite.All` ‏(Application) - رفع الملفات إلى SharePoint
- `Chat.Read.All` ‏(Application) - اختياري، يفعّل روابط المشاركة لكل مستخدم
2. **امنح موافقة المسؤول** للمستأجر.
3. **احصل على معرّف موقع SharePoint الخاص بك:**
```bash
# عبر Graph Explorer أو curl باستخدام token صالح:
curl -H "Authorization: Bearer $TOKEN" \
"https://graph.microsoft.com/v1.0/sites/{hostname}:/{site-path}"
# مثال: لموقع على "contoso.sharepoint.com/sites/BotFiles"
curl -H "Authorization: Bearer $TOKEN" \
"https://graph.microsoft.com/v1.0/sites/contoso.sharepoint.com:/sites/BotFiles"
# تتضمن الاستجابة: "id": "contoso.sharepoint.com,guid1,guid2"
```
4. **اضبط OpenClaw:**
```json5
{
channels: {
msteams: {
// ... إعداد آخر ...
sharePointSiteId: "contoso.sharepoint.com,guid1,guid2",
},
},
}
```
### سلوك المشاركة
| الإذن | سلوك المشاركة |
| ---------------------------------------- | ---------------------------------------------------------- |
| `Sites.ReadWrite.All` فقط | رابط مشاركة على مستوى المؤسسة (يمكن لأي شخص في المؤسسة الوصول) |
| `Sites.ReadWrite.All` + `Chat.Read.All` | رابط مشاركة لكل مستخدم (يمكن فقط لأعضاء الدردشة الوصول) |
تكون المشاركة لكل مستخدم أكثر أمانًا لأن المشاركين في الدردشة فقط يمكنهم الوصول إلى الملف. وإذا كان إذن `Chat.Read.All` مفقودًا، يعود البوت إلى المشاركة على مستوى المؤسسة.
### سلوك الرجوع الاحتياطي
| السيناريو | النتيجة |
| ------------------------------------------------- | --------------------------------------------------- |
| دردشة جماعية + ملف + تم إعداد `sharePointSiteId` | رفع إلى SharePoint وإرسال رابط مشاركة |
| دردشة جماعية + ملف + لا يوجد `sharePointSiteId` | محاولة رفع إلى OneDrive ‏(قد تفشل) وإرسال نص فقط |
| دردشة شخصية + ملف | تدفق FileConsentCard ‏(يعمل بدون SharePoint) |
| أي سياق + صورة | مضمنة داخل الرسالة بترميز Base64 ‏(تعمل بدون SharePoint) |
### موقع تخزين الملفات
تُخزَّن الملفات المرفوعة في مجلد `/OpenClawShared/` داخل مكتبة المستندات الافتراضية لموقع SharePoint المُعد.
## الاستطلاعات (Adaptive Cards)
يرسل OpenClaw استطلاعات Teams على شكل Adaptive Cards ‏(لا توجد Teams poll API أصلية).
- CLI: `openclaw message poll --channel msteams --target conversation:<id> ...`
- تُسجَّل الأصوات بواسطة gateway في `~/.openclaw/msteams-polls.json`.
- يجب أن يبقى gateway متصلًا لتسجيل الأصوات.
- لا تنشر الاستطلاعات تلقائيًا ملخصات النتائج بعدُ (افحص ملف التخزين إذا لزم الأمر).
## Adaptive Cards (عامة)
أرسل أي JSON خاص بـ Adaptive Card إلى مستخدمي Teams أو المحادثات باستخدام أداة `message` أو CLI.
تقبل المعلمة `card` كائن JSON خاص بـ Adaptive Card. وعند توفير `card` يصبح نص الرسالة اختياريًا.
**أداة الوكيل:**
```json5
{
action: "send",
channel: "msteams",
target: "user:<id>",
card: {
type: "AdaptiveCard",
version: "1.5",
body: [{ type: "TextBlock", text: "Hello!" }],
},
}
```
**CLI:**
```bash
openclaw message send --channel msteams \
--target "conversation:19:abc...@thread.tacv2" \
--card '{"type":"AdaptiveCard","version":"1.5","body":[{"type":"TextBlock","text":"Hello!"}]}'
```
راجع [Adaptive Cards documentation](https://adaptivecards.io/) للحصول على مخطط البطاقات والأمثلة. ولتفاصيل تنسيق الأهداف، راجع [تنسيقات الأهداف](#target-formats) أدناه.
## تنسيقات الأهداف
تستخدم أهداف MSTeams بادئات للتمييز بين المستخدمين والمحادثات:
| نوع الهدف | التنسيق | المثال |
| ---------------------- | -------------------------------- | --------------------------------------------------- |
| مستخدم (حسب المعرّف) | `user:<aad-object-id>` | `user:40a1a0ed-4ff2-4164-a219-55518990c197` |
| مستخدم (حسب الاسم) | `user:<display-name>` | `user:John Smith` ‏(يتطلب Graph API) |
| مجموعة/قناة | `conversation:<conversation-id>` | `conversation:19:abc123...@thread.tacv2` |
| مجموعة/قناة (خام) | `<conversation-id>` | `19:abc123...@thread.tacv2` ‏(إذا كان يتضمن `@thread`) |
**أمثلة CLI:**
```bash
# الإرسال إلى مستخدم حسب المعرّف
openclaw message send --channel msteams --target "user:40a1a0ed-..." --message "Hello"
# الإرسال إلى مستخدم حسب اسم العرض (يُفعّل بحث Graph API)
openclaw message send --channel msteams --target "user:John Smith" --message "Hello"
# الإرسال إلى دردشة جماعية أو قناة
openclaw message send --channel msteams --target "conversation:19:abc...@thread.tacv2" --message "Hello"
# إرسال Adaptive Card إلى محادثة
openclaw message send --channel msteams --target "conversation:19:abc...@thread.tacv2" \
--card '{"type":"AdaptiveCard","version":"1.5","body":[{"type":"TextBlock","text":"Hello"}]}'
```
**أمثلة أداة الوكيل:**
```json5
{
action: "send",
channel: "msteams",
target: "user:John Smith",
message: "Hello!",
}
```
```json5
{
action: "send",
channel: "msteams",
target: "conversation:19:abc...@thread.tacv2",
card: {
type: "AdaptiveCard",
version: "1.5",
body: [{ type: "TextBlock", text: "Hello" }],
},
}
```
ملاحظة: من دون البادئة `user:`، تُفسَّر الأسماء افتراضيًا على أنها حل لمجموعة/فريق. استخدم دائمًا `user:` عند استهداف أشخاص باسم العرض.
## المراسلة الاستباقية
- لا يمكن إرسال الرسائل الاستباقية إلا **بعد** أن يتفاعل المستخدم، لأننا نخزن مراجع المحادثات في تلك اللحظة.
- راجع `/gateway/configuration` لمعرفة `dmPolicy` وتقييد قائمة السماح.
## معرّفات الفريق والقناة (مشكلة شائعة)
إن معلمة الاستعلام `groupId` في عناوين URL الخاصة بـ Teams **ليست** معرّف الفريق المستخدم في الإعداد. استخرج المعرّفات من مسار URL بدلًا من ذلك:
**URL الفريق:**
```
https://teams.microsoft.com/l/team/19%3ABk4j...%40thread.tacv2/conversations?groupId=...
└────────────────────────────┘
معرّف الفريق (نفّذ URL-decode لهذا)
```
**URL القناة:**
```
https://teams.microsoft.com/l/channel/19%3A15bc...%40thread.tacv2/ChannelName?groupId=...
└─────────────────────────┘
معرّف القناة (نفّذ URL-decode لهذا)
```
**للإعداد:**
- معرّف الفريق = مقطع المسار بعد `/team/` ‏(بعد URL-decoded، مثل `19:Bk4j...@thread.tacv2`)
- معرّف القناة = مقطع المسار بعد `/channel/` ‏(بعد URL-decoded)
- **تجاهل** معلمة الاستعلام `groupId`
## القنوات الخاصة
تملك البوتات دعمًا محدودًا في القنوات الخاصة:
| الميزة | القنوات القياسية | القنوات الخاصة |
| ---------------------------- | ------------------ | --------------------- |
| تثبيت البوت | نعم | محدود |
| الرسائل الآنية (webhook) | نعم | قد لا تعمل |
| أذونات RSC | نعم | قد تتصرف بشكل مختلف |
| @mentions | نعم | إذا كان البوت متاحًا |
| سجل Graph API | نعم | نعم (مع الأذونات) |
**حلول بديلة إذا لم تعمل القنوات الخاصة:**
1. استخدم القنوات القياسية لتفاعلات البوت
2. استخدم الرسائل المباشرة - يمكن للمستخدمين دائمًا مراسلة البوت مباشرةً
3. استخدم Graph API للوصول إلى السجل التاريخي (يتطلب `ChannelMessage.Read.All`)
## استكشاف الأخطاء وإصلاحها
### مشكلات شائعة
- **الصور لا تظهر في القنوات:** أذونات Graph أو موافقة المسؤول مفقودة. أعد تثبيت تطبيق Teams وأغلق Teams تمامًا ثم أعد فتحه.
- **لا توجد ردود في القناة:** الإشارات مطلوبة افتراضيًا؛ اضبط `channels.msteams.requireMention=false` أو قم بالإعداد لكل فريق/قناة.
- **عدم تطابق الإصدار (ما يزال Teams يعرض manifest قديمًا):** أزل التطبيق ثم أعد إضافته وأغلق Teams تمامًا لتحديثه.
- **401 Unauthorized من webhook:** هذا متوقع عند الاختبار اليدوي من دون Azure JWT - ويعني أن نقطة النهاية قابلة للوصول لكن المصادقة فشلت. استخدم Azure Web Chat للاختبار بشكل صحيح.
### أخطاء رفع manifest
- **"Icon file cannot be empty":** يشير manifest إلى ملفات أيقونات حجمها 0 بايت. أنشئ أيقونات PNG صالحة (`outline.png` بحجم 32x32 و`color.png` بحجم 192x192).
- **"webApplicationInfo.Id already in use":** لا يزال التطبيق مثبتًا في فريق/دردشة أخرى. اعثر عليه وأزل تثبيته أولًا، أو انتظر 5-10 دقائق لانتشار التغيير.
- **"Something went wrong" on upload:** ارفع عبر [https://admin.teams.microsoft.com](https://admin.teams.microsoft.com) بدلًا من ذلك، وافتح أدوات المطور في المتصفح (F12) → علامة Network، ثم تحقق من جسم الاستجابة لرؤية الخطأ الفعلي.
- **فشل التحميل الجانبي:** جرّب "Upload an app to your org's app catalog" بدلًا من "Upload a custom app" - فهذا يتجاوز غالبًا قيود التحميل الجانبي.
### أذونات RSC لا تعمل
1. تحقق من أن `webApplicationInfo.id` يطابق App ID الخاص بالبوت تمامًا
2. أعد رفع التطبيق وأعد تثبيته في الفريق/الدردشة
3. تحقق مما إذا كان مسؤول المؤسسة قد حظر أذونات RSC
4. تأكد من أنك تستخدم النطاق الصحيح: `ChannelMessage.Read.Group` للفرق، و`ChatMessage.Read.Chat` للدردشات الجماعية
## المراجع
- [Create Azure Bot](https://learn.microsoft.com/en-us/azure/bot-service/bot-service-quickstart-registration) - دليل إعداد Azure Bot
- [Teams Developer Portal](https://dev.teams.microsoft.com/apps) - إنشاء/إدارة تطبيقات Teams
- [Teams app manifest schema](https://learn.microsoft.com/en-us/microsoftteams/platform/resources/schema/manifest-schema)
- [Receive channel messages with RSC](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/conversations/channel-messages-with-rsc)
- [RSC permissions reference](https://learn.microsoft.com/en-us/microsoftteams/platform/graph-api/rsc/resource-specific-consent)
- [Teams bot file handling](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/bots-filesv4) ‏(القناة/المجموعة تتطلب Graph)
- [Proactive messaging](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/conversations/send-proactive-messages)
## ذو صلة
- [نظرة عامة على القنوات](/channels) — جميع القنوات المدعومة
- [الإقران](/channels/pairing) — مصادقة الرسائل المباشرة وتدفق الإقران
- [المجموعات](/channels/groups) — سلوك الدردشة الجماعية وتقييد الإشارات
- [توجيه القنوات](/channels/channel-routing) — توجيه الجلسات للرسائل
- [الأمان](/gateway/security) — نموذج الوصول والتقوية

156
docs/ar/channels/nextcloud-talk.md Normal file
View File

@ -0,0 +1,156 @@
---
read_when:
- العمل على ميزات قناة Nextcloud Talk
summary: حالة دعم Nextcloud Talk وإمكاناته وتكوينه
title: Nextcloud Talk
x-i18n:
generated_at: "2026-04-05T12:35:51Z"
model: gpt-5.4
provider: openai
source_hash: 900402afe67cf3ce96103d55158eb28cffb29c9845b77248e70d7653b12ae810
source_path: channels/nextcloud-talk.md
workflow: 15
---
# Nextcloud Talk
الحالة: plugin مضمّن (روبوت webhook). الرسائل المباشرة، والغرف، والتفاعلات، ورسائل markdown مدعومة.
## Plugin مضمّن
يأتي Nextcloud Talk كـ plugin مضمّن في إصدارات OpenClaw الحالية، لذلك
لا تحتاج الإصدارات المجمعة العادية إلى تثبيت منفصل.
إذا كنت تستخدم إصدارًا أقدم أو تثبيتًا مخصصًا لا يتضمن Nextcloud Talk،
فقم بتثبيته يدويًا:
التثبيت عبر CLI (سجل npm):
```bash
openclaw plugins install @openclaw/nextcloud-talk
```
نسخة محلية (عند التشغيل من مستودع git):
```bash
openclaw plugins install ./path/to/local/nextcloud-talk-plugin
```
التفاصيل: [Plugins](/tools/plugin)
## إعداد سريع (للمبتدئين)
1. تأكد من أن plugin الخاص بـ Nextcloud Talk متاح.
- تتضمنه إصدارات OpenClaw المجمعة الحالية بالفعل.
- يمكن لعمليات التثبيت الأقدم/المخصصة إضافته يدويًا بالأوامر أعلاه.
2. على خادم Nextcloud لديك، أنشئ روبوتًا:
```bash
./occ talk:bot:install "OpenClaw" "<shared-secret>" "<webhook-url>" --feature reaction
```
3. فعّل الروبوت في إعدادات الغرفة المستهدفة.
4. اضبط OpenClaw:
- التكوين: `channels.nextcloud-talk.baseUrl` + `channels.nextcloud-talk.botSecret`
- أو متغير البيئة: `NEXTCLOUD_TALK_BOT_SECRET` (للحساب الافتراضي فقط)
5. أعد تشغيل gateway (أو أكمل الإعداد).
الحد الأدنى من التكوين:
```json5
{
channels: {
"nextcloud-talk": {
enabled: true,
baseUrl: "https://cloud.example.com",
botSecret: "shared-secret",
dmPolicy: "pairing",
},
},
}
```
## ملاحظات
- لا يمكن للروبوتات بدء الرسائل المباشرة. يجب أن يراسل المستخدم الروبوت أولًا.
- يجب أن يكون عنوان URL الخاص بـ webhook قابلاً للوصول من Gateway؛ اضبط `webhookPublicUrl` إذا كنت خلف proxy.
- تحميل الوسائط غير مدعوم بواسطة bot API؛ تُرسل الوسائط على شكل عناوين URL.
- لا تميّز حمولة webhook بين الرسائل المباشرة والغرف؛ اضبط `apiUser` + `apiPassword` لتمكين عمليات البحث عن نوع الغرفة (وإلا فستُعامل الرسائل المباشرة على أنها غرف).
## التحكم في الوصول (الرسائل المباشرة)
- الافتراضي: `channels.nextcloud-talk.dmPolicy = "pairing"`. يحصل المرسلون غير المعروفين على رمز pairing.
- وافق عبر:
- `openclaw pairing list nextcloud-talk`
- `openclaw pairing approve nextcloud-talk <CODE>`
- الرسائل المباشرة العامة: `channels.nextcloud-talk.dmPolicy="open"` مع `channels.nextcloud-talk.allowFrom=["*"]`.
- يطابق `allowFrom` معرّفات مستخدمي Nextcloud فقط؛ ويتم تجاهل أسماء العرض.
## الغرف (المجموعات)
- الافتراضي: `channels.nextcloud-talk.groupPolicy = "allowlist"` (مع تقييد الإشارات).
- أضف الغرف إلى قائمة السماح باستخدام `channels.nextcloud-talk.rooms`:
```json5
{
channels: {
"nextcloud-talk": {
rooms: {
"room-token": { requireMention: true },
},
},
},
}
```
- لعدم السماح بأي غرف، اترك قائمة السماح فارغة أو اضبط `channels.nextcloud-talk.groupPolicy="disabled"`.
## الإمكانات
| الميزة | الحالة |
| ---------------- | ------------- |
| الرسائل المباشرة | مدعومة |
| الغرف | مدعومة |
| الخيوط | غير مدعومة |
| الوسائط | عناوين URL فقط |
| التفاعلات | مدعومة |
| الأوامر الأصلية | غير مدعومة |
## مرجع التكوين (Nextcloud Talk)
التكوين الكامل: [Configuration](/gateway/configuration)
خيارات المزوّد:
- `channels.nextcloud-talk.enabled`: تمكين/تعطيل بدء تشغيل القناة.
- `channels.nextcloud-talk.baseUrl`: عنوان URL لنسخة Nextcloud.
- `channels.nextcloud-talk.botSecret`: السر المشترك للروبوت.
- `channels.nextcloud-talk.botSecretFile`: مسار سر لملف عادي. يتم رفض الروابط الرمزية.
- `channels.nextcloud-talk.apiUser`: مستخدم API لعمليات البحث عن الغرف (اكتشاف الرسائل المباشرة).
- `channels.nextcloud-talk.apiPassword`: كلمة مرور API/app لعمليات البحث عن الغرف.
- `channels.nextcloud-talk.apiPasswordFile`: مسار ملف كلمة مرور API.
- `channels.nextcloud-talk.webhookPort`: منفذ مستمع webhook (الافتراضي: 8788).
- `channels.nextcloud-talk.webhookHost`: مضيف webhook (الافتراضي: 0.0.0.0).
- `channels.nextcloud-talk.webhookPath`: مسار webhook (الافتراضي: /nextcloud-talk-webhook).
- `channels.nextcloud-talk.webhookPublicUrl`: عنوان URL خارجي يمكن الوصول إليه لـ webhook.
- `channels.nextcloud-talk.dmPolicy`: ‏`pairing | allowlist | open | disabled`.
- `channels.nextcloud-talk.allowFrom`: قائمة سماح الرسائل المباشرة (معرّفات المستخدمين). يتطلب `open` القيمة `"*"`.
- `channels.nextcloud-talk.groupPolicy`: ‏`allowlist | open | disabled`.
- `channels.nextcloud-talk.groupAllowFrom`: قائمة سماح المجموعات (معرّفات المستخدمين).
- `channels.nextcloud-talk.rooms`: إعدادات لكل غرفة وقائمة السماح.
- `channels.nextcloud-talk.historyLimit`: حد سجل المجموعات (يعطل عند 0).
- `channels.nextcloud-talk.dmHistoryLimit`: حد سجل الرسائل المباشرة (يعطل عند 0).
- `channels.nextcloud-talk.dms`: عمليات تجاوز لكل رسالة مباشرة (`historyLimit`).
- `channels.nextcloud-talk.textChunkLimit`: حجم تجزئة النص الصادر (أحرف).
- `channels.nextcloud-talk.chunkMode`: ‏`length` (الافتراضي) أو `newline` للتقسيم عند الأسطر الفارغة (حدود الفقرات) قبل التجزئة حسب الطول.
- `channels.nextcloud-talk.blockStreaming`: تعطيل block streaming لهذه القناة.
- `channels.nextcloud-talk.blockStreamingCoalesce`: ضبط دمج block streaming.
- `channels.nextcloud-talk.mediaMaxMb`: الحد الأقصى للوسائط الواردة (MB).
## ذو صلة
- [نظرة عامة على القنوات](/channels) — جميع القنوات المدعومة
- [Pairing](/channels/pairing) — مصادقة الرسائل المباشرة وتدفق pairing
- [المجموعات](/channels/groups) — سلوك الدردشة الجماعية وتقييد الإشارات
- [توجيه القنوات](/channels/channel-routing) — توجيه الجلسات للرسائل
- [الأمان](/gateway/security) — نموذج الوصول والتقوية

259
docs/ar/channels/nostr.md Normal file
View File

@ -0,0 +1,259 @@
---
read_when:
- أنت تريد أن يستقبل OpenClaw الرسائل المباشرة عبر Nostr
- أنت تقوم بإعداد مراسلة لامركزية
summary: قناة الرسائل المباشرة Nostr عبر رسائل NIP-04 المشفرة
title: Nostr
x-i18n:
generated_at: "2026-04-05T12:36:01Z"
model: gpt-5.4
provider: openai
source_hash: f82829ee66fbeb3367007af343797140049ea49f2e842a695fa56acea0c80728
source_path: channels/nostr.md
workflow: 15
---
# Nostr
**الحالة:** plugin مضمّن اختياري (معطل افتراضيًا حتى تتم تهيئته).
Nostr هو بروتوكول لامركزي للشبكات الاجتماعية. تتيح هذه القناة لـ OpenClaw استقبال الرسائل المباشرة (DMs) المشفرة والرد عليها عبر NIP-04.
## plugin المضمّن
تشحن إصدارات OpenClaw الحالية Nostr باعتباره plugin مضمّنًا، لذلك لا تحتاج
البنيات المعبأة العادية إلى تثبيت منفصل.
### عمليات التثبيت الأقدم/المخصصة
- لا يزال `openclaw onboard` و`openclaw channels add` يعرضان
Nostr من فهرس القنوات المشترك.
- إذا كان البناء الخاص بك يستبعد Nostr المضمّن، فثبّته يدويًا.
```bash
openclaw plugins install @openclaw/nostr
```
استخدم نسخة checkout محلية (سير عمل التطوير):
```bash
openclaw plugins install --link <path-to-local-nostr-plugin>
```
أعد تشغيل Gateway بعد تثبيت plugins أو تمكينها.
### إعداد غير تفاعلي
```bash
openclaw channels add --channel nostr --private-key "$NOSTR_PRIVATE_KEY"
openclaw channels add --channel nostr --private-key "$NOSTR_PRIVATE_KEY" --relay-urls "wss://relay.damus.io,wss://relay.primal.net"
```
استخدم `--use-env` للاحتفاظ بـ `NOSTR_PRIVATE_KEY` في البيئة بدلًا من تخزين المفتاح في الإعدادات.
## إعداد سريع
1. أنشئ زوج مفاتيح Nostr ‏(إذا لزم الأمر):
```bash
# Using nak
nak key generate
```
2. أضفه إلى الإعدادات:
```json5
{
channels: {
nostr: {
privateKey: "${NOSTR_PRIVATE_KEY}",
},
},
}
```
3. صدّر المفتاح:
```bash
export NOSTR_PRIVATE_KEY="nsec1..."
```
4. أعد تشغيل Gateway.
## مرجع الإعدادات
| المفتاح | النوع | الافتراضي | الوصف |
| ------------ | -------- | ------------------------------------------- | ----------------------------------- |
| `privateKey` | string | مطلوب | المفتاح الخاص بتنسيق `nsec` أو hex |
| `relays` | string[] | `['wss://relay.damus.io', 'wss://nos.lol']` | عناوين URL للـ relay ‏(WebSocket) |
| `dmPolicy` | string | `pairing` | سياسة الوصول للرسائل المباشرة |
| `allowFrom` | string[] | `[]` | مفاتيح pubkeys المسموح بها للمرسلين |
| `enabled` | boolean | `true` | تمكين/تعطيل القناة |
| `name` | string | - | اسم العرض |
| `profile` | object | - | بيانات تعريف ملف NIP-01 |
## بيانات تعريف الملف الشخصي
يتم نشر بيانات الملف الشخصي كحدث NIP-01 من النوع `kind:0`. يمكنك إدارتها من واجهة Control UI ‏(Channels -> Nostr -> Profile) أو ضبطها مباشرة في الإعدادات.
مثال:
```json5
{
channels: {
nostr: {
privateKey: "${NOSTR_PRIVATE_KEY}",
profile: {
name: "openclaw",
displayName: "OpenClaw",
about: "Personal assistant DM bot",
picture: "https://example.com/avatar.png",
banner: "https://example.com/banner.png",
website: "https://example.com",
nip05: "openclaw@example.com",
lud16: "openclaw@example.com",
},
},
},
}
```
ملاحظات:
- يجب أن تستخدم عناوين URL للملف الشخصي `https://`.
- يؤدي الاستيراد من relays إلى دمج الحقول مع الحفاظ على التجاوزات المحلية.
## التحكم في الوصول
### سياسات الرسائل المباشرة
- **pairing** (الافتراضي): يحصل المرسلون غير المعروفين على رمز اقتران.
- **allowlist**: لا يمكن إلا للمفاتيح العامة الموجودة في `allowFrom` إرسال رسائل مباشرة.
- **open**: رسائل مباشرة عامة واردة (يتطلب `allowFrom: ["*"]`).
- **disabled**: تجاهل الرسائل المباشرة الواردة.
ملاحظات التنفيذ:
- يتم التحقق من تواقيع الأحداث الواردة قبل سياسة المرسل وفك تشفير NIP-04، لذلك تُرفض الأحداث المزورة مبكرًا.
- يتم إرسال ردود الاقتران من دون معالجة نص الرسالة المباشرة الأصلي.
- يتم تطبيق حد للمعدل على الرسائل المباشرة الواردة، ويتم إسقاط الحمولات كبيرة الحجم قبل فك التشفير.
### مثال على قائمة السماح
```json5
{
channels: {
nostr: {
privateKey: "${NOSTR_PRIVATE_KEY}",
dmPolicy: "allowlist",
allowFrom: ["npub1abc...", "npub1xyz..."],
},
},
}
```
## تنسيقات المفاتيح
التنسيقات المقبولة:
- **المفتاح الخاص:** `nsec...` أو hex من 64 حرفًا
- **المفاتيح العامة (`allowFrom`):** `npub...` أو hex
## Relays
القيم الافتراضية: `relay.damus.io` و`nos.lol`.
```json5
{
channels: {
nostr: {
privateKey: "${NOSTR_PRIVATE_KEY}",
relays: ["wss://relay.damus.io", "wss://relay.primal.net", "wss://nostr.wine"],
},
},
}
```
نصائح:
- استخدم 2 إلى 3 relays للتكرار.
- تجنب عددًا كبيرًا جدًا من relays ‏(زمن الاستجابة، التكرار).
- يمكن أن تحسن relays المدفوعة الموثوقية.
- relays المحلية مناسبة للاختبار (`ws://localhost:7777`).
## دعم البروتوكول
| NIP | الحالة | الوصف |
| ------ | --------- | ------------------------------------- |
| NIP-01 | مدعوم | تنسيق الحدث الأساسي + بيانات الملف الشخصي |
| NIP-04 | مدعوم | الرسائل المباشرة المشفرة (`kind:4`) |
| NIP-17 | مخطط له | الرسائل المباشرة المغلفة بهدايا |
| NIP-44 | مخطط له | تشفير بإصدارات |
## الاختبار
### Relay محلي
```bash
# Start strfry
docker run -p 7777:7777 ghcr.io/hoytech/strfry
```
```json5
{
channels: {
nostr: {
privateKey: "${NOSTR_PRIVATE_KEY}",
relays: ["ws://localhost:7777"],
},
},
}
```
### اختبار يدوي
1. دوّن المفتاح العام الخاص بالبوت (npub) من السجلات.
2. افتح عميل Nostr ‏(Damus أو Amethyst أو غيرهما).
3. أرسل رسالة مباشرة إلى المفتاح العام الخاص بالبوت.
4. تحقق من الاستجابة.
## استكشاف الأخطاء وإصلاحها
### لا يتم استقبال الرسائل
- تحقّق من أن المفتاح الخاص صالح.
- تأكد من إمكانية الوصول إلى عناوين URL الخاصة بـ relay وأنها تستخدم `wss://` ‏(أو `ws://` للمحلي).
- أكّد أن `enabled` ليس `false`.
- تحقّق من سجلات Gateway بحثًا عن أخطاء اتصال relay.
### لا يتم إرسال الردود
- تحقّق من أن relay يقبل عمليات الكتابة.
- تحقّق من الاتصال الصادر.
- راقب حدود المعدل الخاصة بـ relay.
### ردود مكررة
- هذا متوقع عند استخدام relays متعددة.
- تتم إزالة التكرار من الرسائل حسب معرّف الحدث؛ ولا يؤدي إلا أول تسليم إلى تشغيل رد.
## الأمان
- لا تلتزم أبدًا بالمفاتيح الخاصة في المستودع.
- استخدم متغيرات البيئة للمفاتيح.
- فكّر في استخدام `allowlist` لبوتات الإنتاج.
- يتم التحقق من التواقيع قبل سياسة المرسل، ويتم فرض سياسة المرسل قبل فك التشفير، لذلك تُرفض الأحداث المزورة مبكرًا ولا يمكن للمرسلين غير المعروفين فرض عمل تشفيري كامل.
## القيود (MVP)
- الرسائل المباشرة فقط (من دون دردشات جماعية).
- لا توجد مرفقات وسائط.
- NIP-04 فقط (تغليف الهدايا في NIP-17 مخطط له).
## ذو صلة
- [نظرة عامة على القنوات](/channels) — جميع القنوات المدعومة
- [الاقتران](/channels/pairing) — مصادقة الرسائل المباشرة وتدفق الاقتران
- [المجموعات](/channels/groups) — سلوك دردشات المجموعات وبوابة الإشارات
- [توجيه القنوات](/channels/channel-routing) — توجيه الجلسات للرسائل
- [الأمان](/gateway/security) — نموذج الوصول والتقوية

133
docs/ar/channels/pairing.md Normal file
View File

@ -0,0 +1,133 @@
---
read_when:
- عند إعداد التحكم في الوصول إلى الرسائل المباشرة
- عند إقران عقدة iOS/Android جديدة
- عند مراجعة الوضع الأمني لـ OpenClaw
summary: 'نظرة عامة على الاقتران: الموافقة على من يمكنه مراسلتك مباشرة + أي العقد يمكنها الانضمام'
title: الاقتران
x-i18n:
generated_at: "2026-04-05T12:35:55Z"
model: gpt-5.4
provider: openai
source_hash: 2bd99240b3530def23c05a26915d07cf8b730565c2822c6338437f8fb3f285c9
source_path: channels/pairing.md
workflow: 15
---
# الاقتران
"الاقتران" هو خطوة **موافقة المالك** الصريحة في OpenClaw.
ويُستخدم في موضعين:
1. **اقتران الرسائل المباشرة** (من يُسمح له بالتحدث إلى البوت)
2. **اقتران العقد** (أي الأجهزة/العقد يُسمح لها بالانضمام إلى شبكة البوابة)
السياق الأمني: [الأمان](/gateway/security)
## 1) اقتران الرسائل المباشرة (الوصول إلى الدردشة الواردة)
عندما تُضبط قناة بسياسة رسائل مباشرة `pairing`، يحصل المرسلون غير المعروفين على رمز قصير ولا تتم **معالجة** رسالتهم حتى توافق عليها.
سياسات الرسائل المباشرة الافتراضية موثقة في: [الأمان](/gateway/security)
رموز الاقتران:
- 8 أحرف، بأحرف كبيرة، من دون أحرف ملتبسة (`0O1I`).
- **تنتهي صلاحيتها بعد ساعة واحدة**. لا يرسل البوت رسالة الاقتران إلا عند إنشاء طلب جديد (تقريبًا مرة واحدة كل ساعة لكل مرسل).
- يُحدَّد الحد الأقصى لطلبات اقتران الرسائل المباشرة المعلقة عند **3 لكل قناة** افتراضيًا؛ ويتم تجاهل الطلبات الإضافية حتى تنتهي صلاحية أحدها أو تتم الموافقة عليه.
### الموافقة على مرسل
```bash
openclaw pairing list telegram
openclaw pairing approve telegram <CODE>
```
القنوات المدعومة: `bluebubbles` و`discord` و`feishu` و`googlechat` و`imessage` و`irc` و`line` و`matrix` و`mattermost` و`msteams` و`nextcloud-talk` و`nostr` و`openclaw-weixin` و`signal` و`slack` و`synology-chat` و`telegram` و`twitch` و`whatsapp` و`zalo` و`zalouser`.
### مكان وجود الحالة
تُخزَّن تحت `~/.openclaw/credentials/`:
- الطلبات المعلقة: `<channel>-pairing.json`
- مخزن قائمة السماح المعتمدة:
- الحساب الافتراضي: `<channel>-allowFrom.json`
- الحساب غير الافتراضي: `<channel>-<accountId>-allowFrom.json`
سلوك نطاق الحساب:
- تقرأ الحسابات غير الافتراضية وتكتب فقط إلى ملف قائمة السماح الخاص بنطاقها.
- يستخدم الحساب الافتراضي ملف قائمة السماح غير المقيّد بنطاق الحساب والخاص بالقناة.
تعامل مع هذه الملفات على أنها حساسة (فهي تتحكم في الوصول إلى مساعدك).
مهم: هذا المخزن خاص بوصول الرسائل المباشرة. أما تفويض المجموعات فهو منفصل.
الموافقة على رمز اقتران رسالة مباشرة لا تسمح تلقائيًا لذلك المرسل بتشغيل أوامر المجموعات أو التحكم في البوت داخل المجموعات. بالنسبة إلى وصول المجموعات، اضبط قوائم السماح الصريحة للمجموعات في القناة (مثل `groupAllowFrom` أو `groups` أو التجاوزات الخاصة بكل مجموعة/موضوع بحسب القناة).
## 2) اقتران أجهزة العقد (عقد iOS/Android/macOS/headless)
تتصل العقد بالبوابة كأجهزة ذات `role: node`. وتنشئ البوابة طلب اقتران جهاز يجب الموافقة عليه.
### الإقران عبر Telegram (مستحسن لـ iOS)
إذا كنت تستخدم plugin ‏`device-pair`، فيمكنك تنفيذ اقتران الجهاز لأول مرة بالكامل من Telegram:
1. في Telegram، أرسل إلى البوت: `/pair`
2. يرد البوت برسالتين: رسالة تعليمات ورسالة منفصلة تحتوي على **رمز الإعداد** (ليسهل نسخه/لصقه في Telegram).
3. على هاتفك، افتح تطبيق OpenClaw على iOS → Settings → Gateway.
4. الصق رمز الإعداد واتصل.
5. ارجع إلى Telegram: `/pair pending` (لمراجعة معرّفات الطلبات والدور والنطاقات)، ثم وافق.
رمز الإعداد هو حمولة JSON مشفّرة بـ base64 تحتوي على:
- `url`: عنوان WebSocket URL الخاص بالبوابة (`ws://...` أو `wss://...`)
- `bootstrapToken`: رمز bootstrap قصير العمر لجهاز واحد يُستخدم في مصافحة الاقتران الأولية
يحمل رمز bootstrap هذا ملف تعريف bootstrap المضمّن الخاص بالاقتران:
- يظل رمز `node` الأساسي المُسلَّم بصلاحيات `scopes: []`
- يظل أي رمز `operator` مُسلَّم مقيّدًا بقائمة السماح الخاصة بالـ bootstrap:
`operator.approvals` و`operator.read` و`operator.talk.secrets` و`operator.write`
- تكون عمليات التحقق من نطاق bootstrap مسبوقة بالدور، وليست مجموعة نطاقات مسطحة واحدة:
إدخالات نطاق operator تلبّي فقط طلبات operator، ولا تزال الأدوار غير operator
مطالبة بطلب نطاقات تحت بادئة دورها الخاصة
تعامل مع رمز الإعداد كما تتعامل مع كلمة مرور طوال مدة صلاحيته.
### الموافقة على جهاز عقدة
```bash
openclaw devices list
openclaw devices approve <requestId>
openclaw devices reject <requestId>
```
إذا أعاد الجهاز نفسه المحاولة بتفاصيل مصادقة مختلفة (على سبيل المثال دور/نطاقات/مفتاح عام مختلف)، فسيتم استبدال الطلب المعلق السابق ويُنشأ `requestId` جديد.
### تخزين حالة اقتران العقدة
تُخزَّن تحت `~/.openclaw/devices/`:
- `pending.json` ‏(قصير العمر؛ تنتهي صلاحية الطلبات المعلقة)
- `paired.json` ‏(الأجهزة المقترنة + الرموز)
### ملاحظات
- واجهة `node.pair.*` القديمة (CLI: ‏`openclaw nodes pending|approve|reject|rename`) هي
مخزن اقتران منفصل مملوك للبوابة. ولا تزال عقد WS تتطلب اقتران الأجهزة.
- سجل الاقتران هو المصدر الدائم للحقيقة بالنسبة إلى الأدوار المعتمدة. وتبقى
رموز الأجهزة النشطة مقيّدة بمجموعة الأدوار المعتمدة تلك؛ ولا يؤدي وجود إدخال رمز شارد
خارج الأدوار المعتمدة إلى إنشاء وصول جديد.
## مستندات ذات صلة
- نموذج الأمان + حقن المطالبات: [الأمان](/gateway/security)
- التحديث بأمان (شغّل doctor): [التحديث](/install/updating)
- إعدادات القنوات:
- Telegram: [Telegram](/channels/telegram)
- WhatsApp: [WhatsApp](/channels/whatsapp)
- Signal: [Signal](/channels/signal)
- BlueBubbles ‏(iMessage): [BlueBubbles](/channels/bluebubbles)
- iMessage ‏(قديم): [iMessage](/channels/imessage)
- Discord: [Discord](/channels/discord)
- Slack: [Slack](/channels/slack)

200
docs/ar/channels/qqbot.md Normal file
View File

@ -0,0 +1,200 @@
---
read_when:
- تريد توصيل OpenClaw بـ QQ
- تحتاج إلى إعداد بيانات اعتماد QQ Bot
- تريد دعم QQ Bot للمجموعات أو الدردشة الخاصة
summary: إعداد QQ Bot وتكوينه واستخدامه
title: QQ Bot
x-i18n:
generated_at: "2026-04-05T12:36:09Z"
model: gpt-5.4
provider: openai
source_hash: 0e58fb7b07c59ecbf80a1276368c4a007b45d84e296ed40cffe9845e0953696c
source_path: channels/qqbot.md
workflow: 15
---
# QQ Bot
يتصل QQ Bot بـ OpenClaw عبر QQ Bot API الرسمي (بوابة WebSocket). تدعم
الإضافة الدردشة الخاصة C2C، ورسائل @ في المجموعات، ورسائل قنوات guild مع
وسائط غنية (الصور، والصوت، والفيديو، والملفات).
الحالة: plugin مضمّنة. الرسائل الخاصة، ودردشات المجموعات، وقنوات guild،
والوسائط مدعومة. لا يتم دعم التفاعلات والخيوط.
## plugin المضمّنة
تتضمن إصدارات OpenClaw الحالية QQ Bot، لذلك لا تحتاج الإصدارات المجمعة العادية
إلى خطوة `openclaw plugins install` منفصلة.
## الإعداد
1. انتقل إلى [QQ Open Platform](https://q.qq.com/) وامسح رمز QR باستخدام
تطبيق QQ على هاتفك للتسجيل / تسجيل الدخول.
2. انقر على **Create Bot** لإنشاء QQ bot جديد.
3. اعثر على **AppID** و**AppSecret** في صفحة إعدادات البوت وانسخهما.
> لا يتم تخزين AppSecret كنص عادي — إذا غادرت الصفحة دون حفظه،
> فسيتعين عليك إنشاء واحد جديد.
4. أضف القناة:
```bash
openclaw channels add --channel qqbot --token "AppID:AppSecret"
```
5. أعد تشغيل Gateway.
مسارات الإعداد التفاعلي:
```bash
openclaw channels add
openclaw configure --section channels
```
## التكوين
الحد الأدنى من التكوين:
```json5
{
channels: {
qqbot: {
enabled: true,
appId: "YOUR_APP_ID",
clientSecret: "YOUR_APP_SECRET",
},
},
}
```
متغيرات البيئة للحساب الافتراضي:
- `QQBOT_APP_ID`
- `QQBOT_CLIENT_SECRET`
AppSecret من ملف:
```json5
{
channels: {
qqbot: {
enabled: true,
appId: "YOUR_APP_ID",
clientSecretFile: "/path/to/qqbot-secret.txt",
},
},
}
```
ملاحظات:
- ينطبق الرجوع إلى متغيرات البيئة على حساب QQ Bot الافتراضي فقط.
- يوفّر `openclaw channels add --channel qqbot --token-file ...`
AppSecret فقط؛ ويجب أن يكون AppID مضبوطًا مسبقًا في التكوين أو في `QQBOT_APP_ID`.
- يقبل `clientSecret` أيضًا إدخال SecretRef، وليس فقط سلسلة نصية عادية.
### إعداد متعدد الحسابات
شغّل عدة حسابات QQ bot ضمن مثيل OpenClaw واحد:
```json5
{
channels: {
qqbot: {
enabled: true,
appId: "111111111",
clientSecret: "secret-of-bot-1",
accounts: {
bot2: {
enabled: true,
appId: "222222222",
clientSecret: "secret-of-bot-2",
},
},
},
},
}
```
يشغّل كل حساب اتصال WebSocket خاصًا به ويحافظ على ذاكرة تخزين مؤقت مستقلة
للرمز المميز (معزولة بحسب `appId`).
أضف بوتًا ثانيًا عبر CLI:
```bash
openclaw channels add --channel qqbot --account bot2 --token "222222222:secret-of-bot-2"
```
### الصوت (STT / TTS)
يدعم STT وTTS تكوينًا على مستويين مع رجوع بحسب الأولوية:
| الإعداد | خاص بـ plugin | رجوع الإطار العام |
| ------- | --------------------- | ------------------------------ |
| STT | `channels.qqbot.stt` | `tools.media.audio.models[0]` |
| TTS | `channels.qqbot.tts` | `messages.tts` |
```json5
{
channels: {
qqbot: {
stt: {
provider: "your-provider",
model: "your-stt-model",
},
tts: {
provider: "your-provider",
model: "your-tts-model",
voice: "your-voice",
},
},
},
}
```
اضبط `enabled: false` على أي منهما للتعطيل.
يمكن أيضًا ضبط سلوك رفع/تحويل الصوت الصادر عبر
`channels.qqbot.audioFormatPolicy`:
- `sttDirectFormats`
- `uploadDirectFormats`
- `transcodeEnabled`
## التنسيقات المستهدفة
| التنسيق | الوصف |
| ------------------------- | ------------------ |
| `qqbot:c2c:OPENID` | دردشة خاصة (C2C) |
| `qqbot:group:GROUP_OPENID` | دردشة جماعية |
| `qqbot:channel:CHANNEL_ID` | قناة guild |
> لكل بوت مجموعة OpenID خاصة به للمستخدمين. ولا يمكن
> استخدام OpenID المستلم بواسطة Bot A **لإرسال** رسائل عبر Bot B.
## أوامر الشرطة المائلة
الأوامر المضمنة التي يتم اعتراضها قبل قائمة انتظار الذكاء الاصطناعي:
| الأمر | الوصف |
| -------------- | ------------------------------------- |
| `/bot-ping` | اختبار زمن الاستجابة |
| `/bot-version` | عرض إصدار إطار OpenClaw |
| `/bot-help` | عرض جميع الأوامر |
| `/bot-upgrade` | عرض رابط دليل ترقية QQBot |
| `/bot-logs` | تصدير سجلات Gateway الحديثة كملف |
أضف `?` إلى أي أمر للحصول على مساعدة الاستخدام (على سبيل المثال `/bot-upgrade ?`).
## استكشاف الأخطاء وإصلاحها
- **يرد البوت بعبارة "gone to Mars":** بيانات الاعتماد غير مكوّنة أو لم يتم تشغيل Gateway.
- **لا توجد رسائل واردة:** تحقّق من صحة `appId` و`clientSecret`، ومن
تمكين البوت في QQ Open Platform.
- **لا يزال الإعداد باستخدام `--token-file` يظهر على أنه غير مكوّن:** يضبط `--token-file`
AppSecret فقط. ما زلت بحاجة إلى `appId` في التكوين أو `QQBOT_APP_ID`.
- **لا تصل الرسائل الاستباقية:** قد يعترض QQ الرسائل التي يبدأها البوت إذا
لم يتفاعل المستخدم مؤخرًا.
- **لا يتم تفريغ الصوت إلى نص:** تأكد من تكوين STT وإمكانية الوصول إلى المزوّد.

344
docs/ar/channels/signal.md Normal file
View File

@ -0,0 +1,344 @@
---
read_when:
- إعداد دعم Signal
- تصحيح إرسال/استقبال Signal
summary: دعم Signal عبر signal-cli ‏(JSON-RPC + SSE)، ومسارات الإعداد، ونموذج الأرقام
title: Signal
x-i18n:
generated_at: "2026-04-05T12:36:40Z"
model: gpt-5.4
provider: openai
source_hash: cdd855eb353aca6a1c2b04d14af0e3da079349297b54fa8243562c52b29118d9
source_path: channels/signal.md
workflow: 15
---
# Signal (signal-cli)
الحالة: تكامل CLI خارجي. يتواصل Gateway مع `signal-cli` عبر HTTP JSON-RPC + SSE.
## المتطلبات الأساسية
- تثبيت OpenClaw على خادمك (تم اختبار التدفق أدناه على Ubuntu 24).
- توفر `signal-cli` على المضيف الذي يعمل عليه gateway.
- رقم هاتف يمكنه استلام رسالة SMS واحدة للتحقق (لمسار التسجيل عبر SMS).
- إمكانية الوصول عبر المتصفح إلى captcha الخاصة بـ Signal (`signalcaptchas.org`) أثناء التسجيل.
## إعداد سريع (للمبتدئين)
1. استخدم **رقم Signal منفصلًا** للروبوت (موصى به).
2. ثبّت `signal-cli` (يتطلب Java إذا كنت تستخدم إصدار JVM).
3. اختر أحد مساري الإعداد:
- **المسار A (ربط QR):** ‏`signal-cli link -n "OpenClaw"` ثم امسح الرمز باستخدام Signal.
- **المسار B (تسجيل SMS):** سجّل رقمًا مخصصًا باستخدام captcha + التحقق عبر SMS.
4. اضبط OpenClaw وأعد تشغيل gateway.
5. أرسل أول رسالة مباشرة ووافق على pairing (`openclaw pairing approve signal <CODE>`).
الحد الأدنى من التكوين:
```json5
{
channels: {
signal: {
enabled: true,
account: "+15551234567",
cliPath: "signal-cli",
dmPolicy: "pairing",
allowFrom: ["+15557654321"],
},
},
}
```
مرجع الحقول:
| الحقل | الوصف |
| ----------- | ---------------------------------------------------- |
| `account` | رقم هاتف الروبوت بتنسيق E.164 ‏(`+15551234567`) |
| `cliPath` | مسار `signal-cli` ‏(`signal-cli` إذا كان على `PATH`) |
| `dmPolicy` | سياسة الوصول إلى الرسائل المباشرة (`pairing` موصى به) |
| `allowFrom` | أرقام الهواتف أو قيم `uuid:<id>` المسموح لها بإرسال رسائل مباشرة |
## ما هو
- قناة Signal عبر `signal-cli` (وليست libsignal مضمّنة).
- توجيه حتمي: تذهب الردود دائمًا إلى Signal.
- تشارك الرسائل المباشرة الجلسة الرئيسية للوكيل؛ بينما تكون المجموعات معزولة (`agent:<agentId>:signal:group:<groupId>`).
## عمليات كتابة التكوين
بشكل افتراضي، يُسمح لـ Signal بكتابة تحديثات التكوين التي يتم تشغيلها بواسطة `/config set|unset` (يتطلب `commands.config: true`).
للتعطيل:
```json5
{
channels: { signal: { configWrites: false } },
}
```
## نموذج الرقم (مهم)
- يتصل gateway بـ **جهاز Signal** (حساب `signal-cli`).
- إذا شغّلت الروبوت على **حساب Signal الشخصي** الخاص بك، فسيتجاهل رسائلك أنت (حماية من الحلقة).
- للحصول على سلوك "أرسل رسالة إلى الروبوت فيرد"، استخدم **رقم روبوت منفصلًا**.
## مسار الإعداد A: ربط حساب Signal موجود (QR)
1. ثبّت `signal-cli` (إصدار JVM أو الإصدار الأصلي).
2. اربط حساب روبوت:
- `signal-cli link -n "OpenClaw"` ثم امسح QR في Signal.
3. اضبط Signal وابدأ gateway.
مثال:
```json5
{
channels: {
signal: {
enabled: true,
account: "+15551234567",
cliPath: "signal-cli",
dmPolicy: "pairing",
allowFrom: ["+15557654321"],
},
},
}
```
دعم الحسابات المتعددة: استخدم `channels.signal.accounts` مع تكوين لكل حساب و`name` اختياري. راجع [`gateway/configuration`](/gateway/configuration-reference#multi-account-all-channels) للنمط المشترك.
## مسار الإعداد B: تسجيل رقم روبوت مخصص (SMS، Linux)
استخدم هذا إذا كنت تريد رقم روبوت مخصصًا بدلًا من ربط حساب تطبيق Signal موجود.
1. احصل على رقم يمكنه استلام SMS (أو التحقق الصوتي للهواتف الأرضية).
- استخدم رقم روبوت مخصصًا لتجنب تعارضات الحساب/الجلسة.
2. ثبّت `signal-cli` على مضيف gateway:
```bash
VERSION=$(curl -Ls -o /dev/null -w %{url_effective} https://github.com/AsamK/signal-cli/releases/latest | sed -e 's/^.*\/v//')
curl -L -O "https://github.com/AsamK/signal-cli/releases/download/v${VERSION}/signal-cli-${VERSION}-Linux-native.tar.gz"
sudo tar xf "signal-cli-${VERSION}-Linux-native.tar.gz" -C /opt
sudo ln -sf /opt/signal-cli /usr/local/bin/
signal-cli --version
```
إذا كنت تستخدم إصدار JVM ‏(`signal-cli-${VERSION}.tar.gz`)، فثبّت JRE 25+ أولًا.
احرص على تحديث `signal-cli`؛ إذ تشير ملاحظات المنبع إلى أن الإصدارات القديمة قد تتعطل مع تغيّر واجهات Signal server API.
3. سجّل الرقم وتحقق منه:
```bash
signal-cli -a +<BOT_PHONE_NUMBER> register
```
إذا كانت captcha مطلوبة:
1. افتح `https://signalcaptchas.org/registration/generate.html`.
2. أكمل captcha، ثم انسخ هدف الرابط `signalcaptcha://...` من "Open Signal".
3. شغّل من نفس عنوان IP الخارجي الخاص بجلسة المتصفح إن أمكن.
4. أعد تشغيل التسجيل فورًا (تنتهي صلاحية رموز captcha بسرعة):
```bash
signal-cli -a +<BOT_PHONE_NUMBER> register --captcha '<SIGNALCAPTCHA_URL>'
signal-cli -a +<BOT_PHONE_NUMBER> verify <VERIFICATION_CODE>
```
4. اضبط OpenClaw، وأعد تشغيل gateway، وتحقق من القناة:
```bash
# If you run the gateway as a user systemd service:
systemctl --user restart openclaw-gateway.service
# Then verify:
openclaw doctor
openclaw channels status --probe
```
5. نفّذ pairing لمرسل الرسائل المباشرة:
- أرسل أي رسالة إلى رقم الروبوت.
- وافق على الرمز على الخادم: `openclaw pairing approve signal <PAIRING_CODE>`.
- احفظ رقم الروبوت كجهة اتصال على هاتفك لتجنب "Unknown contact".
مهم: قد يؤدي تسجيل حساب رقم هاتف باستخدام `signal-cli` إلى إلغاء مصادقة جلسة تطبيق Signal الرئيسية لذلك الرقم. يُفضّل استخدام رقم روبوت مخصص، أو استخدام وضع الربط عبر QR إذا كنت بحاجة إلى الاحتفاظ بإعداد تطبيق الهاتف الحالي.
مراجع المنبع:
- ملف `signal-cli` README: ‏`https://github.com/AsamK/signal-cli`
- تدفق captcha: ‏`https://github.com/AsamK/signal-cli/wiki/Registration-with-captcha`
- تدفق الربط: ‏`https://github.com/AsamK/signal-cli/wiki/Linking-other-devices-(Provisioning)`
## وضع daemon الخارجي (httpUrl)
إذا كنت تريد إدارة `signal-cli` بنفسك (بطء التشغيل الأولي لـ JVM، أو تهيئة الحاوية، أو وحدات CPU مشتركة)، فشغّل daemon بشكل منفصل ووجّه OpenClaw إليه:
```json5
{
channels: {
signal: {
httpUrl: "http://127.0.0.1:8080",
autoStart: false,
},
},
}
```
يتجاوز هذا التشغيل التلقائي والانتظار عند بدء التشغيل داخل OpenClaw. عند بطء البدء أثناء التشغيل التلقائي، اضبط `channels.signal.startupTimeoutMs`.
## التحكم في الوصول (الرسائل المباشرة + المجموعات)
الرسائل المباشرة:
- الافتراضي: `channels.signal.dmPolicy = "pairing"`.
- يتلقى المرسلون غير المعروفين رمز pairing؛ ويتم تجاهل الرسائل حتى الموافقة عليها (تنتهي صلاحية الرموز بعد ساعة واحدة).
- تتم الموافقة عبر:
- `openclaw pairing list signal`
- `openclaw pairing approve signal <CODE>`
- pairing هو تبادل الرموز الافتراضي لرسائل Signal المباشرة. التفاصيل: [Pairing](/channels/pairing)
- يتم تخزين المرسلين الذين لديهم UUID فقط (من `sourceUuid`) كـ `uuid:<id>` في `channels.signal.allowFrom`.
المجموعات:
- `channels.signal.groupPolicy = open | allowlist | disabled`.
- يتحكم `channels.signal.groupAllowFrom` في من يمكنه التفعيل في المجموعات عند تعيين `allowlist`.
- يمكن لـ `channels.signal.groups["<group-id>" | "*"]` تجاوز سلوك المجموعات باستخدام `requireMention` و`tools` و`toolsBySender`.
- استخدم `channels.signal.accounts.<id>.groups` لعمليات التجاوز لكل حساب في إعدادات الحسابات المتعددة.
- ملاحظة وقت التشغيل: إذا كان `channels.signal` مفقودًا بالكامل، فسيعود وقت التشغيل إلى `groupPolicy="allowlist"` لفحوصات المجموعات (حتى إذا تم تعيين `channels.defaults.groupPolicy`).
## كيف يعمل (السلوك)
- يعمل `signal-cli` كـ daemon؛ ويقرأ gateway الأحداث عبر SSE.
- تُطبّع الرسائل الواردة إلى غلاف القناة المشترك.
- تُوجَّه الردود دائمًا إلى الرقم أو المجموعة نفسها.
## الوسائط والحدود
- يُجزّأ النص الصادر إلى `channels.signal.textChunkLimit` (الافتراضي 4000).
- تجزئة اختيارية حسب الأسطر الجديدة: اضبط `channels.signal.chunkMode="newline"` للتقسيم عند الأسطر الفارغة (حدود الفقرات) قبل التجزئة حسب الطول.
- المرفقات مدعومة (يتم جلب base64 من `signal-cli`).
- الحد الافتراضي للوسائط: `channels.signal.mediaMaxMb` (الافتراضي 8).
- استخدم `channels.signal.ignoreAttachments` لتخطي تنزيل الوسائط.
- يستخدم سياق سجل المجموعات `channels.signal.historyLimit` (أو `channels.signal.accounts.*.historyLimit`) مع الرجوع إلى `messages.groupChat.historyLimit`. اضبط `0` للتعطيل (الافتراضي 50).
## مؤشرات الكتابة وإيصالات القراءة
- **مؤشرات الكتابة**: يرسل OpenClaw إشارات الكتابة عبر `signal-cli sendTyping` ويحدّثها أثناء تشغيل الرد.
- **إيصالات القراءة**: عندما تكون `channels.signal.sendReadReceipts` صحيحة، يمرر OpenClaw إيصالات القراءة للرسائل المباشرة المسموح بها.
- لا يوفّر Signal-cli إيصالات قراءة للمجموعات.
## التفاعلات (أداة الرسائل)
- استخدم `message action=react` مع `channel=signal`.
- الأهداف: E.164 للمرسل أو UUID (استخدم `uuid:<id>` من مخرجات pairing؛ يعمل UUID الخام أيضًا).
- `messageId` هو الطابع الزمني في Signal للرسالة التي تتفاعل معها.
- تتطلب تفاعلات المجموعات `targetAuthor` أو `targetAuthorUuid`.
أمثلة:
```
message action=react channel=signal target=uuid:123e4567-e89b-12d3-a456-426614174000 messageId=1737630212345 emoji=🔥
message action=react channel=signal target=+15551234567 messageId=1737630212345 emoji=🔥 remove=true
message action=react channel=signal target=signal:group:<groupId> targetAuthor=uuid:<sender-uuid> messageId=1737630212345 emoji=✅
```
التكوين:
- `channels.signal.actions.reactions`: تمكين/تعطيل إجراءات التفاعل (الافتراضي true).
- `channels.signal.reactionLevel`: ‏`off | ack | minimal | extensive`.
- يؤدي `off`/`ack` إلى تعطيل تفاعلات الوكيل (وستُرجع أداة الرسائل `react` خطأ).
- يفعّل `minimal`/`extensive` تفاعلات الوكيل ويحددان مستوى الإرشاد.
- عمليات تجاوز لكل حساب: `channels.signal.accounts.<id>.actions.reactions` و`channels.signal.accounts.<id>.reactionLevel`.
## أهداف التسليم (CLI/cron)
- الرسائل المباشرة: `signal:+15551234567` (أو E.164 عادي).
- الرسائل المباشرة عبر UUID: ‏`uuid:<id>` (أو UUID خام).
- المجموعات: `signal:group:<groupId>`.
- أسماء المستخدمين: `username:<name>` (إذا كان حساب Signal لديك يدعمها).
## استكشاف الأخطاء وإصلاحها
شغّل هذا التسلسل أولًا:
```bash
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe
```
ثم تأكد من حالة pairing للرسائل المباشرة إذا لزم الأمر:
```bash
openclaw pairing list signal
```
الأعطال الشائعة:
- يمكن الوصول إلى daemon ولكن لا توجد ردود: تحقق من إعدادات الحساب/daemon (`httpUrl`, `account`) ووضع الاستقبال.
- يتم تجاهل الرسائل المباشرة: المرسل بانتظار موافقة pairing.
- يتم تجاهل رسائل المجموعات: تقييد المرسل/الإشارة في المجموعة يمنع التسليم.
- أخطاء التحقق من التكوين بعد التعديلات: شغّل `openclaw doctor --fix`.
- غياب Signal من أدوات التشخيص: تأكد من `channels.signal.enabled: true`.
فحوصات إضافية:
```bash
openclaw pairing list signal
pgrep -af signal-cli
grep -i "signal" "/tmp/openclaw/openclaw-$(date +%Y-%m-%d).log" | tail -20
```
لتدفق الفرز: [/channels/troubleshooting](/channels/troubleshooting).
## ملاحظات أمنية
- يخزّن `signal-cli` مفاتيح الحساب محليًا (عادةً `~/.local/share/signal-cli/data/`).
- انسخ حالة حساب Signal احتياطيًا قبل ترحيل الخادم أو إعادة بنائه.
- أبقِ `channels.signal.dmPolicy: "pairing"` ما لم تكن تريد صراحةً وصولًا أوسع للرسائل المباشرة.
- لا يلزم التحقق عبر SMS إلا لمسارات التسجيل أو الاستعادة، لكن فقدان التحكم في الرقم/الحساب قد يعقّد إعادة التسجيل.
## مرجع التكوين (Signal)
التكوين الكامل: [Configuration](/gateway/configuration)
خيارات المزوّد:
- `channels.signal.enabled`: تمكين/تعطيل بدء تشغيل القناة.
- `channels.signal.account`: E.164 لحساب الروبوت.
- `channels.signal.cliPath`: مسار `signal-cli`.
- `channels.signal.httpUrl`: عنوان URL الكامل للـ daemon (يتجاوز المضيف/المنفذ).
- `channels.signal.httpHost`, `channels.signal.httpPort`: ربط daemon ‏(الافتراضي 127.0.0.1:8080).
- `channels.signal.autoStart`: تشغيل daemon تلقائيًا (الافتراضي true إذا لم يتم تعيين `httpUrl`).
- `channels.signal.startupTimeoutMs`: مهلة انتظار بدء التشغيل بالمللي ثانية (الحد الأقصى 120000).
- `channels.signal.receiveMode`: ‏`on-start | manual`.
- `channels.signal.ignoreAttachments`: تخطي تنزيل المرفقات.
- `channels.signal.ignoreStories`: تجاهل القصص من daemon.
- `channels.signal.sendReadReceipts`: تمرير إيصالات القراءة.
- `channels.signal.dmPolicy`: ‏`pairing | allowlist | open | disabled` (الافتراضي: pairing).
- `channels.signal.allowFrom`: قائمة سماح الرسائل المباشرة (E.164 أو `uuid:<id>`). يتطلب `open` القيمة `"*"`. لا يملك Signal أسماء مستخدمين؛ استخدم معرّفات الهاتف/UUID.
- `channels.signal.groupPolicy`: ‏`open | allowlist | disabled` (الافتراضي: allowlist).
- `channels.signal.groupAllowFrom`: قائمة سماح مرسلي المجموعات.
- `channels.signal.groups`: عمليات تجاوز لكل مجموعة بمفتاح معرّف مجموعة Signal (أو `"*"`). الحقول المدعومة: `requireMention` و`tools` و`toolsBySender`.
- `channels.signal.accounts.<id>.groups`: النسخة الخاصة بكل حساب من `channels.signal.groups` لإعدادات الحسابات المتعددة.
- `channels.signal.historyLimit`: الحد الأقصى لرسائل المجموعات المضمنة كسياق (يعطل عند 0).
- `channels.signal.dmHistoryLimit`: حد سجل الرسائل المباشرة بوحدات أدوار المستخدم. عمليات تجاوز لكل مستخدم: `channels.signal.dms["<phone_or_uuid>"].historyLimit`.
- `channels.signal.textChunkLimit`: حجم التجزئة الصادرة (أحرف).
- `channels.signal.chunkMode`: ‏`length` (الافتراضي) أو `newline` للتقسيم عند الأسطر الفارغة (حدود الفقرات) قبل التجزئة حسب الطول.
- `channels.signal.mediaMaxMb`: الحد الأقصى للوسائط الواردة/الصادرة (MB).
خيارات عامة ذات صلة:
- `agents.list[].groupChat.mentionPatterns` (لا يدعم Signal الإشارات الأصلية).
- `messages.groupChat.mentionPatterns` (الرجوع العام).
- `messages.responsePrefix`.
## ذو صلة
- [نظرة عامة على القنوات](/channels) — جميع القنوات المدعومة
- [Pairing](/channels/pairing) — مصادقة الرسائل المباشرة وتدفق pairing
- [المجموعات](/channels/groups) — سلوك الدردشة الجماعية وتقييد الإشارات
- [توجيه القنوات](/channels/channel-routing) — توجيه الجلسات للرسائل
- [الأمان](/gateway/security) — نموذج الوصول والتقوية

688
docs/ar/channels/slack.md Normal file
View File

@ -0,0 +1,688 @@
---
read_when:
- عند إعداد Slack أو تصحيح وضع socket/HTTP في Slack
summary: إعداد Slack وسلوك وقت التشغيل (Socket Mode + HTTP Events API)
title: Slack
x-i18n:
generated_at: "2026-04-05T12:37:12Z"
model: gpt-5.4
provider: openai
source_hash: efb37e1f04e1ac8ac3786c36ffc20013dacdc654bfa61e7f6e8df89c4902d2ab
source_path: channels/slack.md
workflow: 15
---
# Slack
الحالة: جاهز للإنتاج للرسائل المباشرة + القنوات عبر تكاملات تطبيق Slack. الوضع الافتراضي هو Socket Mode؛ كما أن وضع HTTP Events API مدعوم أيضًا.
<CardGroup cols={3}>
<Card title="الاقتران" icon="link" href="/channels/pairing">
تستخدم الرسائل المباشرة في Slack وضع الاقتران افتراضيًا.
</Card>
<Card title="أوامر slash" icon="terminal" href="/tools/slash-commands">
سلوك الأوامر الأصلي وكتالوج الأوامر.
</Card>
<Card title="استكشاف أخطاء القنوات وإصلاحها" icon="wrench" href="/channels/troubleshooting">
تشخيصات عبر القنوات وأدلة إصلاح.
</Card>
</CardGroup>
## الإعداد السريع
<Tabs>
<Tab title="Socket Mode (الافتراضي)">
<Steps>
<Step title="أنشئ تطبيق Slack والرموز">
في إعدادات تطبيق Slack:
- فعّل **Socket Mode**
- أنشئ **App Token** (`xapp-...`) مع `connections:write`
- ثبّت التطبيق وانسخ **Bot Token** (`xoxb-...`)
</Step>
<Step title="إعداد OpenClaw">
```json5
{
channels: {
slack: {
enabled: true,
mode: "socket",
appToken: "xapp-...",
botToken: "xoxb-...",
},
},
}
```
الرجوع إلى البيئة (للحساب الافتراضي فقط):
```bash
SLACK_APP_TOKEN=xapp-...
SLACK_BOT_TOKEN=xoxb-...
```
</Step>
<Step title="اشترك في أحداث التطبيق">
اشترك في أحداث البوت التالية:
- `app_mention`
- `message.channels`, `message.groups`, `message.im`, `message.mpim`
- `reaction_added`, `reaction_removed`
- `member_joined_channel`, `member_left_channel`
- `channel_rename`
- `pin_added`, `pin_removed`
فعّل أيضًا App Home **Messages Tab** للرسائل المباشرة.
</Step>
<Step title="ابدأ البوابة">
```bash
openclaw gateway
```
</Step>
</Steps>
</Tab>
<Tab title="وضع HTTP Events API">
<Steps>
<Step title="إعداد تطبيق Slack لـ HTTP">
- اضبط الوضع على HTTP (`channels.slack.mode="http"`)
- انسخ **Signing Secret** الخاص بـ Slack
- اضبط عنوان Request URL لاشتراكات الأحداث + التفاعلية + أوامر Slash على مسار webhook نفسه (الافتراضي `/slack/events`)
</Step>
<Step title="إعداد وضع HTTP في OpenClaw">
```json5
{
channels: {
slack: {
enabled: true,
mode: "http",
botToken: "xoxb-...",
signingSecret: "your-signing-secret",
webhookPath: "/slack/events",
},
},
}
```
</Step>
<Step title="استخدم مسارات webhook فريدة للحسابات المتعددة عبر HTTP">
وضع HTTP لكل حساب مدعوم.
امنح كل حساب `webhookPath` مختلفًا حتى لا تتصادم التسجيلات.
</Step>
</Steps>
</Tab>
</Tabs>
## قائمة التحقق من manifest والنطاقات
<AccordionGroup>
<Accordion title="مثال على manifest لتطبيق Slack" defaultOpen>
```json
{
"display_information": {
"name": "OpenClaw",
"description": "Slack connector for OpenClaw"
},
"features": {
"bot_user": {
"display_name": "OpenClaw",
"always_online": true
},
"app_home": {
"messages_tab_enabled": true,
"messages_tab_read_only_enabled": false
},
"slash_commands": [
{
"command": "/openclaw",
"description": "Send a message to OpenClaw",
"should_escape": false
}
]
},
"oauth_config": {
"scopes": {
"bot": [
"app_mentions:read",
"assistant:write",
"channels:history",
"channels:read",
"chat:write",
"commands",
"emoji:read",
"files:read",
"files:write",
"groups:history",
"groups:read",
"im:history",
"im:read",
"im:write",
"mpim:history",
"mpim:read",
"mpim:write",
"pins:read",
"pins:write",
"reactions:read",
"reactions:write",
"users:read"
]
}
},
"settings": {
"socket_mode_enabled": true,
"event_subscriptions": {
"bot_events": [
"app_mention",
"channel_rename",
"member_joined_channel",
"member_left_channel",
"message.channels",
"message.groups",
"message.im",
"message.mpim",
"pin_added",
"pin_removed",
"reaction_added",
"reaction_removed"
]
}
}
}
```
</Accordion>
<Accordion title="نطاقات user-token الاختيارية (عمليات القراءة)">
إذا قمت بإعداد `channels.slack.userToken`، فإن نطاقات القراءة النموذجية هي:
- `channels:history`, `groups:history`, `im:history`, `mpim:history`
- `channels:read`, `groups:read`, `im:read`, `mpim:read`
- `users:read`
- `reactions:read`
- `pins:read`
- `emoji:read`
- `search:read` (إذا كنت تعتمد على قراءات البحث في Slack)
</Accordion>
</AccordionGroup>
## نموذج الرموز
- `botToken` + `appToken` مطلوبان لـ Socket Mode.
- يتطلب وضع HTTP كلاً من `botToken` + `signingSecret`.
- يقبل `botToken` و`appToken` و`signingSecret` و`userToken` سلاسل نصية صريحة
أو كائنات SecretRef.
- تتجاوز الرموز في الإعداد قيم الرجوع إلى البيئة.
- ينطبق الرجوع إلى متغيرات البيئة `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` على الحساب الافتراضي فقط.
- `userToken` (`xoxp-...`) للإعداد فقط (لا يوجد رجوع إلى البيئة) ويستخدم سلوك القراءة فقط افتراضيًا (`userTokenReadOnly: true`).
- اختياري: أضف `chat:write.customize` إذا كنت تريد أن تستخدم الرسائل الصادرة هوية الوكيل النشطة (اسم مستخدم `username` مخصص وأيقونة). يستخدم `icon_emoji` صيغة `:emoji_name:`.
سلوك لقطة الحالة:
- يتتبع فحص حساب Slack حقول `*Source` و`*Status`
لكل بيانات اعتماد (`botToken` و`appToken` و`signingSecret` و`userToken`).
- تكون الحالة إحدى القيم: `available` أو `configured_unavailable` أو `missing`.
- تعني `configured_unavailable` أن الحساب مُعدّ عبر SecretRef
أو مصدر أسرار آخر غير مضمن، ولكن مسار الأمر/وقت التشغيل الحالي
لم يتمكن من حل القيمة الفعلية.
- في وضع HTTP، يتم تضمين `signingSecretStatus`؛ وفي Socket Mode، يكون
الزوج المطلوب هو `botTokenStatus` + `appTokenStatus`.
<Tip>
بالنسبة إلى الإجراءات/قراءات الدليل، يمكن تفضيل user token عند إعداده. أما بالنسبة إلى عمليات الكتابة، فيظل bot token هو المفضل؛ ولا يُسمح بعمليات الكتابة عبر user-token إلا عندما يكون `userTokenReadOnly: false` وbot token غير متاح.
</Tip>
## الإجراءات والبوابات
تتحكم `channels.slack.actions.*` في إجراءات Slack.
مجموعات الإجراءات المتاحة في أدوات Slack الحالية:
| المجموعة | الافتراضي |
| ---------- | ------- |
| messages | مفعّل |
| reactions | مفعّل |
| pins | مفعّل |
| memberInfo | مفعّل |
| emojiList | مفعّل |
تتضمن إجراءات رسائل Slack الحالية `send` و`upload-file` و`download-file` و`read` و`edit` و`delete` و`pin` و`unpin` و`list-pins` و`member-info` و`emoji-list`.
## التحكم في الوصول والتوجيه
<Tabs>
<Tab title="سياسة الرسائل المباشرة">
تتحكم `channels.slack.dmPolicy` في الوصول إلى الرسائل المباشرة (القديم: `channels.slack.dm.policy`):
- `pairing` (الافتراضي)
- `allowlist`
- `open` (يتطلب أن يتضمن `channels.slack.allowFrom` القيمة `"*"`؛ القديم: `channels.slack.dm.allowFrom`)
- `disabled`
علامات الرسائل المباشرة:
- `dm.enabled` (الافتراضي true)
- `channels.slack.allowFrom` (المفضل)
- `dm.allowFrom` (قديم)
- `dm.groupEnabled` (الرسائل المباشرة الجماعية default false)
- `dm.groupChannels` (قائمة سماح MPIM اختيارية)
أسبقية الحسابات المتعددة:
- ينطبق `channels.slack.accounts.default.allowFrom` على الحساب `default` فقط.
- ترث الحسابات المسماة `channels.slack.allowFrom` عندما لا تكون `allowFrom` الخاصة بها مضبوطة.
- لا ترث الحسابات المسماة `channels.slack.accounts.default.allowFrom`.
يستخدم الاقتران في الرسائل المباشرة `openclaw pairing approve slack <code>`.
</Tab>
<Tab title="سياسة القنوات">
تتحكم `channels.slack.groupPolicy` في معالجة القنوات:
- `open`
- `allowlist`
- `disabled`
توجد قائمة السماح للقنوات ضمن `channels.slack.channels` ويجب أن تستخدم معرّفات قنوات ثابتة.
ملاحظة وقت التشغيل: إذا كان `channels.slack` مفقودًا بالكامل (إعداد يعتمد على البيئة فقط)، فسيعود وقت التشغيل إلى `groupPolicy="allowlist"` ويسجل تحذيرًا (حتى إذا كان `channels.defaults.groupPolicy` مضبوطًا).
تحليل الاسم/المعرّف:
- يتم تحليل مدخلات قائمة السماح للقنوات ومدخلات قائمة السماح للرسائل المباشرة عند بدء التشغيل عندما يتيح وصول الرمز ذلك
- تُحتفظ بمدخلات أسماء القنوات غير المحلولة كما هي في الإعداد، لكنها تُتجاهل افتراضيًا في التوجيه
- يعتمد التفويض الوارد وتوجيه القنوات على المعرّف أولاً افتراضيًا؛ وتتطلب مطابقة اسم المستخدم/الاسم المختصر مباشرة ضبط `channels.slack.dangerouslyAllowNameMatching: true`
</Tab>
<Tab title="الإشارات ومستخدمي القنوات">
رسائل القنوات مقيّدة بالإشارة افتراضيًا.
مصادر الإشارة:
- إشارة صريحة إلى التطبيق (`<@botId>`)
- أنماط regex للإشارة (`agents.list[].groupChat.mentionPatterns`، والرجوع إلى `messages.groupChat.mentionPatterns`)
- سلوك الرد الضمني على سلسلة خاصة بالبوت
عناصر التحكم لكل قناة (`channels.slack.channels.<id>`؛ الأسماء فقط عبر التحليل عند بدء التشغيل أو `dangerouslyAllowNameMatching`):
- `requireMention`
- `users` (قائمة سماح)
- `allowBots`
- `skills`
- `systemPrompt`
- `tools`, `toolsBySender`
- صيغة مفتاح `toolsBySender`: ‏`id:` أو `e164:` أو `username:` أو `name:` أو wildcard `"*"`
(لا تزال المفاتيح القديمة غير المسبوقة تُربط إلى `id:` فقط)
</Tab>
</Tabs>
## سلاسل المحادثات والجلسات وعلامات الرد
- يتم توجيه الرسائل المباشرة كـ `direct`؛ والقنوات كـ `channel`؛ وMPIMs كـ `group`.
- مع الإعداد الافتراضي `session.dmScope=main`، تُدمج الرسائل المباشرة في Slack ضمن الجلسة الرئيسية للوكيل.
- جلسات القنوات: `agent:<agentId>:slack:channel:<channelId>`.
- يمكن أن تنشئ ردود السلاسل لاحقات جلسة للسلسلة (`:thread:<threadTs>`) عند الاقتضاء.
- القيمة الافتراضية لـ `channels.slack.thread.historyScope` هي `thread`؛ والقيمة الافتراضية لـ `thread.inheritParent` هي `false`.
- يتحكم `channels.slack.thread.initialHistoryLimit` في عدد رسائل السلسلة الموجودة التي تُجلب عند بدء جلسة سلسلة جديدة (الافتراضي `20`؛ اضبطه إلى `0` للتعطيل).
عناصر التحكم في سلاسل الرد:
- `channels.slack.replyToMode`: ‏`off|first|all` (الافتراضي `off`)
- `channels.slack.replyToModeByChatType`: لكل من `direct|group|channel`
- الرجوع القديم للدردشات المباشرة: `channels.slack.dm.replyToMode`
علامات الرد اليدوية مدعومة:
- `[[reply_to_current]]`
- `[[reply_to:<id>]]`
ملاحظة: يعطّل `replyToMode="off"` **كل** سلاسل الرد في Slack، بما في ذلك علامات `[[reply_to_*]]` الصريحة. وهذا يختلف عن Telegram، حيث تظل العلامات الصريحة محترمة في وضع `"off"`. ويعكس هذا الاختلاف نماذج السلاسل في المنصات: تخفي سلاسل Slack الرسائل عن القناة، بينما تظل ردود Telegram مرئية في تدفق الدردشة الرئيسي.
## تفاعلات التأكيد
يرسل `ackReaction` رمزًا تعبيريًا للتأكيد بينما يعالج OpenClaw رسالة واردة.
ترتيب التحليل:
- `channels.slack.accounts.<accountId>.ackReaction`
- `channels.slack.ackReaction`
- `messages.ackReaction`
- الرجوع إلى emoji هوية الوكيل (`agents.list[].identity.emoji`، وإلا "👀")
ملاحظات:
- يتوقع Slack shortcodes (على سبيل المثال `"eyes"`).
- استخدم `""` لتعطيل التفاعل لحساب Slack أو على مستوى عام.
## بث النص
يتحكم `channels.slack.streaming` في سلوك المعاينة المباشرة:
- `off`: تعطيل بث المعاينة المباشرة.
- `partial` (الافتراضي): استبدال نص المعاينة بآخر مخرجات جزئية.
- `block`: إلحاق تحديثات معاينة مجزأة.
- `progress`: إظهار نص حالة التقدم أثناء التوليد، ثم إرسال النص النهائي.
يتحكم `channels.slack.nativeStreaming` في البث النصي الأصلي في Slack عندما تكون `streaming` هي `partial` (الافتراضي: `true`).
- يجب أن تكون سلسلة رد متاحة حتى يظهر البث النصي الأصلي. ولا يزال اختيار السلسلة يتبع `replyToMode`. ومن دونها، تُستخدم معاينة المسودة العادية.
- تعود الوسائط والحمولات غير النصية إلى التسليم العادي.
- إذا فشل البث في منتصف الرد، يعود OpenClaw إلى التسليم العادي للحمولات المتبقية.
استخدم معاينة المسودة بدلًا من البث النصي الأصلي في Slack:
```json5
{
channels: {
slack: {
streaming: "partial",
nativeStreaming: false,
},
},
}
```
المفاتيح القديمة:
- تتم الترحيل التلقائي لـ `channels.slack.streamMode` (`replace | status_final | append`) إلى `channels.slack.streaming`.
- تتم الترحيل التلقائي لـ boolean `channels.slack.streaming` إلى `channels.slack.nativeStreaming`.
## الرجوع إلى تفاعل الكتابة
يضيف `typingReaction` تفاعلًا مؤقتًا إلى رسالة Slack الواردة بينما يعالج OpenClaw ردًا، ثم يزيله عند انتهاء التشغيل. وهذا مفيد أكثر خارج ردود السلاسل، التي تستخدم مؤشر حالة افتراضي "is typing...".
ترتيب التحليل:
- `channels.slack.accounts.<accountId>.typingReaction`
- `channels.slack.typingReaction`
ملاحظات:
- يتوقع Slack shortcodes (على سبيل المثال `"hourglass_flowing_sand"`).
- التفاعل best-effort وتتم محاولة تنظيفه تلقائيًا بعد اكتمال الرد أو مسار الفشل.
## الوسائط والتجزئة والتسليم
<AccordionGroup>
<Accordion title="المرفقات الواردة">
تُنزَّل مرفقات ملفات Slack من عناوين URL خاصة مستضافة لدى Slack (تدفق طلبات موثَّق بالرمز) وتُكتب في مخزن الوسائط عند نجاح الجلب والسماح بحدود الحجم.
الحد الأقصى للحجم الوارد في وقت التشغيل يكون افتراضيًا `20MB` ما لم يتم تجاوزه عبر `channels.slack.mediaMaxMb`.
</Accordion>
<Accordion title="النصوص والملفات الصادرة">
- تستخدم مقاطع النص `channels.slack.textChunkLimit` (الافتراضي 4000)
- يفعّل `channels.slack.chunkMode="newline"` التقسيم بحسب الفقرات أولًا
- تستخدم عمليات إرسال الملفات واجهات Slack upload API ويمكن أن تتضمن ردود سلاسل (`thread_ts`)
- يتبع الحد الأقصى للوسائط الصادرة `channels.slack.mediaMaxMb` عند إعداده؛ وإلا فتستخدم عمليات الإرسال في القنوات القيم الافتراضية حسب نوع MIME من media pipeline
</Accordion>
<Accordion title="أهداف التسليم">
الأهداف الصريحة المفضلة:
- `user:<id>` للرسائل المباشرة
- `channel:<id>` للقنوات
تُفتح الرسائل المباشرة في Slack عبر Slack conversation APIs عند الإرسال إلى أهداف المستخدمين.
</Accordion>
</AccordionGroup>
## الأوامر وسلوك slash
- الوضع التلقائي للأوامر الأصلية **معطّل** في Slack (`commands.native: "auto"` لا يفعّل أوامر Slack الأصلية).
- فعّل معالجات أوامر Slack الأصلية باستخدام `channels.slack.commands.native: true` (أو الإعداد العام `commands.native: true`).
- عند تفعيل الأوامر الأصلية، سجّل أوامر slash المطابقة في Slack (أسماء `/<command>`)، مع استثناء واحد:
- سجّل `/agentstatus` لأمر الحالة (يحجز Slack الاسم `/status`)
- إذا لم تكن الأوامر الأصلية مفعّلة، فيمكنك تشغيل أمر slash واحد مُعدّ عبر `channels.slack.slashCommand`.
- تتكيف قوائم الوسائط الأصلية للوسائط مع إستراتيجية العرض:
- حتى 5 خيارات: كتل أزرار
- من 6 إلى 100 خيار: قائمة اختيار ثابتة
- أكثر من 100 خيار: اختيار خارجي مع تصفية خيارات غير متزامنة عند توفر معالجات خيارات التفاعلية
- إذا تجاوزت قيم الخيارات المشفّرة حدود Slack، يعود التدفق إلى الأزرار
- بالنسبة إلى حمولات الخيارات الطويلة، تستخدم قوائم وسائط معاملات أوامر Slash مربع حوار تأكيد قبل إرسال القيمة المحددة.
إعدادات أوامر slash الافتراضية:
- `enabled: false`
- `name: "openclaw"`
- `sessionPrefix: "slack:slash"`
- `ephemeral: true`
تستخدم جلسات Slash مفاتيح معزولة:
- `agent:<agentId>:slack:slash:<userId>`
ومع ذلك تظل توجّه تنفيذ الأمر إلى جلسة المحادثة المستهدفة (`CommandTargetSessionKey`).
## الردود التفاعلية
يمكن لـ Slack عرض عناصر تحكم تفاعلية للردود التي أنشأها الوكيل، لكن هذه الميزة معطلة افتراضيًا.
فعّلها على مستوى عام:
```json5
{
channels: {
slack: {
capabilities: {
interactiveReplies: true,
},
},
},
}
```
أو فعّلها لحساب Slack واحد فقط:
```json5
{
channels: {
slack: {
accounts: {
ops: {
capabilities: {
interactiveReplies: true,
},
},
},
},
},
}
```
عند التفعيل، يمكن للوكلاء إصدار توجيهات رد خاصة بـ Slack فقط:
- `[[slack_buttons: Approve:approve, Reject:reject]]`
- `[[slack_select: Choose a target | Canary:canary, Production:production]]`
تُترجم هذه التوجيهات إلى Slack Block Kit وتعيد توجيه النقرات أو التحديدات عبر مسار أحداث تفاعل Slack الحالي.
ملاحظات:
- هذه واجهة مستخدم خاصة بـ Slack. لا تترجم القنوات الأخرى توجيهات Slack Block Kit إلى أنظمة الأزرار الخاصة بها.
- قيم ردود النداء التفاعلية هي رموز opaque مولدة من OpenClaw، وليست قيمًا خام كتبها الوكيل.
- إذا كانت الكتل التفاعلية المولدة ستتجاوز حدود Slack Block Kit، فسيعود OpenClaw إلى الرد النصي الأصلي بدلًا من إرسال حمولة blocks غير صالحة.
## موافقات exec في Slack
يمكن أن يعمل Slack كعميل موافقة أصلي مع أزرار وتفاعلات تفاعلية، بدلًا من الرجوع إلى Web UI أو الطرفية.
- تستخدم موافقات exec المسار `channels.slack.execApprovals.*` للتوجيه الأصلي في الرسائل المباشرة/القنوات.
- لا تزال موافقات plugin تُحل عبر سطح أزرار Slack الأصلي نفسه عندما يصل الطلب بالفعل إلى Slack ويكون نوع معرّف الموافقة هو `plugin:`.
- لا يزال تفويض الموافقين مفروضًا: لا يمكن سوى للمستخدمين المحددين كموافقين الموافقة على الطلبات أو رفضها عبر Slack.
يستخدم هذا سطح أزرار الموافقة المشتركة نفسه كما في القنوات الأخرى. عندما تكون `interactivity` مفعّلة في إعدادات تطبيق Slack لديك، تُعرض مطالبات الموافقة كأزرار Block Kit مباشرة في المحادثة.
عند وجود هذه الأزرار، تكون هي تجربة الاستخدام الأساسية للموافقة؛ ويجب على OpenClaw
أن يدرج أمر `/approve` يدويًا فقط عندما تشير نتيجة الأداة إلى أن
الموافقات عبر الدردشة غير متاحة أو أن الموافقة اليدوية هي المسار الوحيد.
مسار الإعداد:
- `channels.slack.execApprovals.enabled`
- `channels.slack.execApprovals.approvers` (اختياري؛ يعود إلى `commands.ownerAllowFrom` عندما يكون ممكنًا)
- `channels.slack.execApprovals.target` (`dm` | `channel` | `both`، الافتراضي: `dm`)
- `agentFilter`, `sessionFilter`
يفعّل Slack موافقات exec الأصلية تلقائيًا عندما تكون `enabled` غير مضبوطة أو `"auto"` ويوجد موافق واحد محلول على الأقل.
اضبط `enabled: false` لتعطيل Slack كعميل موافقة أصلي صراحةً.
واضبط `enabled: true` لفرض تشغيل الموافقات الأصلية عند حل الموافقين.
السلوك الافتراضي من دون إعداد صريح لموافقات exec في Slack:
```json5
{
commands: {
ownerAllowFrom: ["slack:U12345678"],
},
}
```
يلزم إعداد Slack أصلي صريح فقط عندما تريد تجاوز الموافقين أو إضافة عوامل تصفية أو
تفعيل التسليم إلى دردشة المنشأ:
```json5
{
channels: {
slack: {
execApprovals: {
enabled: true,
approvers: ["U12345678"],
target: "both",
},
},
},
}
```
إن إعادة توجيه `approvals.exec` المشتركة منفصلة. استخدمها فقط عندما يجب أن تُوجَّه مطالبات موافقة exec أيضًا
إلى دردشات أخرى أو أهداف صريحة خارج النطاق. كما أن إعادة توجيه `approvals.plugin` المشتركة منفصلة أيضًا؛
ولا تزال أزرار Slack الأصلية قادرة على حل موافقات plugin عندما تصل هذه الطلبات بالفعل
إلى Slack.
كما يعمل `/approve` في الدردشة نفسها داخل قنوات Slack والرسائل المباشرة التي تدعم الأوامر بالفعل. راجع [موافقات Exec](/tools/exec-approvals) للحصول على نموذج إعادة توجيه الموافقات الكامل.
## الأحداث والسلوك التشغيلي
- تُربط تعديلات الرسائل/حذفها/بث السلاسل بأحداث النظام.
- تُربط أحداث إضافة/إزالة التفاعلات بأحداث النظام.
- تُربط أحداث انضمام/مغادرة الأعضاء، وإنشاء/إعادة تسمية القنوات، وإضافة/إزالة التثبيتات بأحداث النظام.
- يمكن لـ `channel_id_changed` ترحيل مفاتيح إعداد القنوات عندما يكون `configWrites` مفعّلًا.
- تُعامل بيانات topic/purpose الخاصة بالقناة كسياق غير موثوق ويمكن حقنها في سياق التوجيه.
- تُصفّى بادئات السلاسل وسياق تهيئة سجل السلسلة الأولي بحسب قوائم السماح المكونة للمرسلين عند الاقتضاء.
- تصدر إجراءات الكتل وتفاعلات النوافذ المنظمة أحداث نظام منظمة باسم `Slack interaction: ...` مع حقول حمولة غنية:
- إجراءات الكتل: القيم المحددة، والتسميات، وقيم المحددات، وبيانات `workflow_*`
- أحداث `view_submission` و`view_closed` الخاصة بالنوافذ مع بيانات القنوات الموجهة ومدخلات النماذج
## مؤشرات مرجع الإعداد
المرجع الأساسي:
- [مرجع الإعداد - Slack](/gateway/configuration-reference#slack)
الحقول الأبرز في Slack:
- الوضع/المصادقة: `mode`, `botToken`, `appToken`, `signingSecret`, `webhookPath`, `accounts.*`
- الوصول إلى الرسائل المباشرة: `dm.enabled`, `dmPolicy`, `allowFrom` (القديم: `dm.policy`, `dm.allowFrom`), `dm.groupEnabled`, `dm.groupChannels`
- مفتاح التوافق: `dangerouslyAllowNameMatching` (للطوارئ؛ اتركه معطّلًا ما لم تكن بحاجة إليه)
- الوصول إلى القنوات: `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention`
- السلاسل/السجل: `replyToMode`, `replyToModeByChatType`, `thread.*`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit`
- التسليم: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `streaming`, `nativeStreaming`
- العمليات/الميزات: `configWrites`, `commands.native`, `slashCommand.*`, `actions.*`, `userToken`, `userTokenReadOnly`
## استكشاف الأخطاء وإصلاحها
<AccordionGroup>
<Accordion title="لا توجد ردود في القنوات">
تحقّق، بالترتيب، من:
- `groupPolicy`
- قائمة السماح للقنوات (`channels.slack.channels`)
- `requireMention`
- قائمة السماح `users` لكل قناة
أوامر مفيدة:
```bash
openclaw channels status --probe
openclaw logs --follow
openclaw doctor
```
</Accordion>
<Accordion title="يتم تجاهل رسائل DM">
تحقّق من:
- `channels.slack.dm.enabled`
- `channels.slack.dmPolicy` (أو القديم `channels.slack.dm.policy`)
- موافقات الاقتران / إدخالات قائمة السماح
```bash
openclaw pairing list slack
```
</Accordion>
<Accordion title="وضع Socket لا يتصل">
تحقّق من bot token + app token ومن تفعيل Socket Mode في إعدادات تطبيق Slack.
إذا أظهر `openclaw channels status --probe --json` أن `botTokenStatus` أو
`appTokenStatus: "configured_unavailable"`، فهذا يعني أن حساب Slack
مُعدّ لكنه لم يتمكن وقت التشغيل الحالي من حل القيمة
المدعومة بـ SecretRef.
</Accordion>
<Accordion title="وضع HTTP لا يستقبل الأحداث">
تحقّق من:
- signing secret
- مسار webhook
- عناوين Slack Request URL ‏(الأحداث + التفاعلية + أوامر Slash)
- `webhookPath` فريد لكل حساب HTTP
إذا ظهر `signingSecretStatus: "configured_unavailable"` في لقطات
الحساب، فهذا يعني أن حساب HTTP مُعدّ لكن وقت التشغيل الحالي لم يتمكن
من حل signing secret المدعوم بـ SecretRef.
</Accordion>
<Accordion title="الأوامر الأصلية/slash لا تعمل">
تحقّق مما إذا كنت تقصد:
- وضع الأوامر الأصلية (`channels.slack.commands.native: true`) مع تسجيل أوامر slash المطابقة في Slack
- أو وضع أمر slash واحد (`channels.slack.slashCommand.enabled: true`)
وتحقق أيضًا من `commands.useAccessGroups` وقوائم سماح القنوات/المستخدمين.
</Accordion>
</AccordionGroup>
## ذو صلة
- [الاقتران](/channels/pairing)
- [المجموعات](/channels/groups)
- [الأمان](/gateway/security)
- [توجيه القنوات](/channels/channel-routing)
- [استكشاف الأخطاء وإصلاحها](/channels/troubleshooting)
- [الإعداد](/gateway/configuration)
- [أوامر slash](/tools/slash-commands)

192
docs/ar/channels/synology-chat.md Normal file
View File

@ -0,0 +1,192 @@
---
read_when:
- إعداد Synology Chat مع OpenClaw
- تصحيح مسار توجيه webhook في Synology Chat
summary: إعداد webhook لـ Synology Chat وإعدادات OpenClaw
title: Synology Chat
x-i18n:
generated_at: "2026-04-05T12:36:28Z"
model: gpt-5.4
provider: openai
source_hash: ddb25fc6b53f896f15f43b4936d69ea071a29a91838a5b662819377271e89d81
source_path: channels/synology-chat.md
workflow: 15
---
# Synology Chat
الحالة: قناة رسائل مباشرة عبر plugin مضمّن باستخدام webhooks لـ Synology Chat.
يقبل plugin الرسائل الواردة من webhooks الصادرة في Synology Chat ويرسل الردود
عبر webhook وارد في Synology Chat.
## plugin المضمّن
يأتي Synology Chat كـ plugin مضمّن في إصدارات OpenClaw الحالية، لذلك لا تحتاج
البنيات المعبأة العادية إلى تثبيت منفصل.
إذا كنت تستخدم إصدارًا أقدم أو تثبيتًا مخصصًا يستبعد Synology Chat،
فثبّته يدويًا:
ثبّت من نسخة checkout محلية:
```bash
openclaw plugins install ./path/to/local/synology-chat-plugin
```
التفاصيل: [Plugins](/tools/plugin)
## إعداد سريع
1. تأكد من أن plugin الخاص بـ Synology Chat متاح.
- تتضمنه إصدارات OpenClaw المعبأة الحالية بالفعل.
- يمكن لعمليات التثبيت الأقدم/المخصصة إضافته يدويًا من نسخة checkout للمصدر باستخدام الأمر أعلاه.
- يعرض `openclaw onboard` الآن Synology Chat في قائمة إعداد القنوات نفسها الموجودة في `openclaw channels add`.
- إعداد غير تفاعلي: `openclaw channels add --channel synology-chat --token <token> --url <incoming-webhook-url>`
2. في عمليات التكامل الخاصة بـ Synology Chat:
- أنشئ webhook واردًا وانسخ عنوان URL الخاص به.
- أنشئ webhook صادرًا باستخدام رمزك السري.
3. وجّه عنوان URL الخاص بـ webhook الصادر إلى OpenClaw gateway:
- `https://gateway-host/webhook/synology` افتراضيًا.
- أو `channels.synology-chat.webhookPath` المخصص لديك.
4. أكمل الإعداد في OpenClaw.
- بإرشاد: `openclaw onboard`
- مباشرة: `openclaw channels add --channel synology-chat --token <token> --url <incoming-webhook-url>`
5. أعد تشغيل gateway وأرسل رسالة مباشرة إلى بوت Synology Chat.
تفاصيل مصادقة webhook:
- يقبل OpenClaw رمز webhook الصادر من `body.token`، ثم
`?token=...`، ثم الترويسات.
- صيغ الترويسات المقبولة:
- `x-synology-token`
- `x-webhook-token`
- `x-openclaw-token`
- `Authorization: Bearer <token>`
- تفشل الرموز الفارغة أو المفقودة بشكل مغلق.
إعداد أدنى:
```json5
{
channels: {
"synology-chat": {
enabled: true,
token: "synology-outgoing-token",
incomingUrl: "https://nas.example.com/webapi/entry.cgi?api=SYNO.Chat.External&method=incoming&version=2&token=...",
webhookPath: "/webhook/synology",
dmPolicy: "allowlist",
allowedUserIds: ["123456"],
rateLimitPerMinute: 30,
allowInsecureSsl: false,
},
},
}
```
## متغيرات البيئة
بالنسبة إلى الحساب الافتراضي، يمكنك استخدام متغيرات البيئة:
- `SYNOLOGY_CHAT_TOKEN`
- `SYNOLOGY_CHAT_INCOMING_URL`
- `SYNOLOGY_NAS_HOST`
- `SYNOLOGY_ALLOWED_USER_IDS` (مفصولة بفواصل)
- `SYNOLOGY_RATE_LIMIT`
- `OPENCLAW_BOT_NAME`
تتجاوز قيم الإعدادات متغيرات البيئة.
## سياسة الرسائل المباشرة والتحكم في الوصول
- `dmPolicy: "allowlist"` هو الإعداد الافتراضي الموصى به.
- يقبل `allowedUserIds` قائمة بمعرّفات مستخدمي Synology (أو سلسلة مفصولة بفواصل).
- في وضع `allowlist`، تُعامل قائمة `allowedUserIds` الفارغة على أنها خطأ في الإعداد، ولن يبدأ مسار webhook (استخدم `dmPolicy: "open"` للسماح للجميع).
- `dmPolicy: "open"` يسمح لأي مرسل.
- `dmPolicy: "disabled"` يحظر الرسائل المباشرة.
- يبقى ربط مستلم الرد على `user_id` الرقمي المستقر افتراضيًا. ويعد `channels.synology-chat.dangerouslyAllowNameMatching: true` وضع توافق احتياطي يعيد تمكين البحث باسم المستخدم/الاسم المستعار القابل للتغيير لتسليم الردود.
- تعمل موافقات الاقتران باستخدام:
- `openclaw pairing list synology-chat`
- `openclaw pairing approve synology-chat <CODE>`
## التسليم الصادر
استخدم معرّفات مستخدمي Synology Chat الرقمية كأهداف.
أمثلة:
```bash
openclaw message send --channel synology-chat --target 123456 --text "Hello from OpenClaw"
openclaw message send --channel synology-chat --target synology-chat:123456 --text "Hello again"
```
إرسال الوسائط مدعوم عبر تسليم الملفات المستند إلى URL.
## حسابات متعددة
يتم دعم عدة حسابات Synology Chat ضمن `channels.synology-chat.accounts`.
يمكن لكل حساب تجاوز الرمز، وعنوان URL الوارد، ومسار webhook، وسياسة الرسائل المباشرة، والحدود.
تكون جلسات الرسائل المباشرة معزولة لكل حساب ولكل مستخدم، لذلك فإن `user_id` الرقمي نفسه
في حسابين مختلفين من Synology لا يشارك حالة السجل.
أعطِ كل حساب مفعّل قيمة `webhookPath` مختلفة. يرفض OpenClaw الآن المسارات المتطابقة الدقيقة
ويرفض بدء الحسابات المسماة التي ترث فقط مسار webhook مشتركًا في إعدادات الحسابات المتعددة.
إذا كنت تحتاج عمدًا إلى الوراثة القديمة لحساب مسمى، فاضبط
`dangerouslyAllowInheritedWebhookPath: true` على ذلك الحساب أو على `channels.synology-chat`،
لكن المسارات المتطابقة الدقيقة لا تزال تُرفض بشكل مغلق. فضّل المسارات الصريحة لكل حساب.
```json5
{
channels: {
"synology-chat": {
enabled: true,
accounts: {
default: {
token: "token-a",
incomingUrl: "https://nas-a.example.com/...token=...",
},
alerts: {
token: "token-b",
incomingUrl: "https://nas-b.example.com/...token=...",
webhookPath: "/webhook/synology-alerts",
dmPolicy: "allowlist",
allowedUserIds: ["987654"],
},
},
},
},
}
```
## ملاحظات الأمان
- احتفظ بسرية `token` وبدّله إذا تسرّب.
- أبقِ `allowInsecureSsl: false` ما لم تكن تثق صراحةً في شهادة NAS محلية موقعة ذاتيًا.
- يتم التحقق من طلبات webhook الواردة بواسطة الرمز وتطبيق حد معدل عليها لكل مرسل.
- تستخدم فحوصات الرمز غير الصالح مقارنة أسرار بزمن ثابت وتفشل بشكل مغلق.
- فضّل `dmPolicy: "allowlist"` في بيئات الإنتاج.
- أبقِ `dangerouslyAllowNameMatching` معطّلًا ما لم تكن تحتاج صراحةً إلى تسليم الردود القديم المستند إلى اسم المستخدم.
- أبقِ `dangerouslyAllowInheritedWebhookPath` معطّلًا ما لم تكن تقبل صراحةً مخاطر التوجيه عبر المسار المشترك في إعداد حسابات متعددة.
## استكشاف الأخطاء وإصلاحها
- `Missing required fields (token, user_id, text)`:
- حمولة webhook الصادر تفتقد أحد الحقول المطلوبة
- إذا كان Synology يرسل الرمز في الترويسات، فتأكد من أن gateway/proxy يحافظ على تلك الترويسات
- `Invalid token`:
- سر webhook الصادر لا يطابق `channels.synology-chat.token`
- الطلب يصل إلى الحساب أو مسار webhook الخاطئ
- قام reverse proxy بإزالة ترويسة الرمز قبل أن يصل الطلب إلى OpenClaw
- `Rate limit exceeded`:
- قد يؤدي عدد كبير جدًا من محاولات الرمز غير الصالح من المصدر نفسه إلى حظر ذلك المصدر مؤقتًا
- يملك المرسلون الموثقون أيضًا حد معدل رسائل منفصلًا لكل مستخدم
- `Allowlist is empty. Configure allowedUserIds or use dmPolicy=open.`:
- تم تمكين `dmPolicy="allowlist"` لكن لم يتم إعداد أي مستخدمين
- `User not authorized`:
- `user_id` الرقمي للمرسل غير موجود في `allowedUserIds`
## ذو صلة
- [نظرة عامة على القنوات](/channels) — جميع القنوات المدعومة
- [الاقتران](/channels/pairing) — مصادقة الرسائل المباشرة وتدفق الاقتران
- [المجموعات](/channels/groups) — سلوك الدردشة الجماعية وبوابة الإشارات
- [توجيه القنوات](/channels/channel-routing) — توجيه الجلسات للرسائل
- [الأمان](/gateway/security) — نموذج الوصول والتقوية

1079
docs/ar/channels/telegram.md Normal file
View File

File diff suppressed because it is too large Load Diff

297
docs/ar/channels/tlon.md Normal file
View File

@ -0,0 +1,297 @@
---
read_when:
- العمل على ميزات قناة Tlon/Urbit
summary: حالة دعم Tlon/Urbit، والقدرات، والتكوين
title: Tlon
x-i18n:
generated_at: "2026-04-05T12:36:45Z"
model: gpt-5.4
provider: openai
source_hash: 289cffb3c1b2d450a5f41e0d67117dfb5c192cec956d82039caac9df9f07496d
source_path: channels/tlon.md
workflow: 15
---
# Tlon
Tlon هو تطبيق مراسلة لامركزي مبني على Urbit. يتصل OpenClaw بسفينة Urbit الخاصة بك ويمكنه
الرد على الرسائل الخاصة ورسائل الدردشة الجماعية. تتطلب الردود في المجموعات إشارة @ افتراضيًا ويمكن
تقييدها بشكل إضافي عبر قوائم السماح.
الحالة: plugin مضمّن. الرسائل الخاصة، والإشارات في المجموعات، والردود ضمن السلاسل، وتنسيق النص المنسق،
ورفع الصور مدعومة. أما التفاعلات واستطلاعات الرأي فليست مدعومة بعد.
## plugin المضمّن
يأتي Tlon كـ plugin مضمّن في إصدارات OpenClaw الحالية، لذلك لا تحتاج الإصدارات المعبأة
العادية إلى تثبيت منفصل.
إذا كنت تستخدم إصدارًا أقدم أو تثبيتًا مخصصًا لا يتضمن Tlon، فثبّته
يدويًا:
التثبيت عبر CLI ‏(سجل npm):
```bash
openclaw plugins install @openclaw/tlon
```
نسخة محلية (عند التشغيل من مستودع git):
```bash
openclaw plugins install ./path/to/local/tlon-plugin
```
التفاصيل: [Plugins](/tools/plugin)
## الإعداد
1. تأكد من أن plugin Tlon متاح.
- تتضمن إصدارات OpenClaw المعبأة الحالية هذا plugin بالفعل.
- يمكن للتثبيتات الأقدم/المخصصة إضافته يدويًا باستخدام الأوامر أعلاه.
2. اجمع عنوان URL الخاص بالسفينة ورمز تسجيل الدخول.
3. قم بتكوين `channels.tlon`.
4. أعد تشغيل gateway.
5. أرسل رسالة خاصة إلى bot أو أشر إليه في قناة جماعية.
الحد الأدنى من التكوين (حساب واحد):
```json5
{
channels: {
tlon: {
enabled: true,
ship: "~sampel-palnet",
url: "https://your-ship-host",
code: "lidlut-tabwed-pillex-ridrup",
ownerShip: "~your-main-ship", // موصى به: سفينتك، ومسموح بها دائمًا
},
},
}
```
## السفن الخاصة/على LAN
افتراضيًا، يمنع OpenClaw أسماء المضيفين ونطاقات IP الخاصة/الداخلية للحماية من SSRF.
إذا كانت سفينتك تعمل على شبكة خاصة (localhost أو عنوان IP على LAN أو اسم مضيف داخلي)،
فيجب عليك الاشتراك صراحةً:
```json5
{
channels: {
tlon: {
url: "http://localhost:8080",
allowPrivateNetwork: true,
},
},
}
```
ينطبق هذا على عناوين URL مثل:
- `http://localhost:8080`
- `http://192.168.x.x:8080`
- `http://my-ship.local:8080`
⚠️ فعّل هذا فقط إذا كنت تثق بشبكتك المحلية. يعطّل هذا الإعداد حمايات SSRF
للطلبات المرسلة إلى عنوان URL الخاص بسفينتك.
## قنوات المجموعات
يكون الاكتشاف التلقائي ممكّنًا افتراضيًا. يمكنك أيضًا تثبيت القنوات يدويًا:
```json5
{
channels: {
tlon: {
groupChannels: ["chat/~host-ship/general", "chat/~host-ship/support"],
},
},
}
```
تعطيل الاكتشاف التلقائي:
```json5
{
channels: {
tlon: {
autoDiscoverChannels: false,
},
},
}
```
## التحكم في الوصول
قائمة السماح للرسائل الخاصة (فارغة = لا يُسمح بأي رسائل خاصة، استخدم `ownerShip` لتدفق الموافقة):
```json5
{
channels: {
tlon: {
dmAllowlist: ["~zod", "~nec"],
},
},
}
```
تفويض المجموعات (مقيّد افتراضيًا):
```json5
{
channels: {
tlon: {
defaultAuthorizedShips: ["~zod"],
authorization: {
channelRules: {
"chat/~host-ship/general": {
mode: "restricted",
allowedShips: ["~zod", "~nec"],
},
"chat/~host-ship/announcements": {
mode: "open",
},
},
},
},
},
}
```
## نظام المالك والموافقة
عيّن سفينة مالك لتلقي طلبات الموافقة عندما يحاول مستخدمون غير مصرح لهم التفاعل:
```json5
{
channels: {
tlon: {
ownerShip: "~your-main-ship",
},
},
}
```
تكون سفينة المالك **مصرحًا لها تلقائيًا في كل مكان** — تتم الموافقة تلقائيًا على دعوات الرسائل الخاصة،
وتُسمح رسائل القنوات دائمًا. لا تحتاج إلى إضافة المالك إلى `dmAllowlist` أو
`defaultAuthorizedShips`.
عند تعيينه، يتلقى المالك إشعارات عبر الرسائل الخاصة بشأن:
- طلبات الرسائل الخاصة من سفن غير موجودة في قائمة السماح
- الإشارات في القنوات من دون تفويض
- طلبات دعوات المجموعات
## إعدادات القبول التلقائي
القبول التلقائي لدعوات الرسائل الخاصة (للسفن الموجودة في dmAllowlist):
```json5
{
channels: {
tlon: {
autoAcceptDmInvites: true,
},
},
}
```
القبول التلقائي لدعوات المجموعات:
```json5
{
channels: {
tlon: {
autoAcceptGroupInvites: true,
},
},
}
```
## أهداف التسليم (CLI/cron)
استخدم هذه مع `openclaw message send` أو تسليم cron:
- رسالة خاصة: `~sampel-palnet` أو `dm/~sampel-palnet`
- مجموعة: `chat/~host-ship/channel` أو `group:~host-ship/channel`
## Skill المضمّنة
يتضمن plugin Tlon Skill مضمّنة ([`@tloncorp/tlon-skill`](https://github.com/tloncorp/tlon-skill))
توفر وصولًا عبر CLI إلى عمليات Tlon:
- **جهات الاتصال**: الحصول على الملفات الشخصية/تحديثها، وسرد جهات الاتصال
- **القنوات**: السرد، والإنشاء، ونشر الرسائل، وجلب السجل
- **المجموعات**: السرد، والإنشاء، وإدارة الأعضاء
- **الرسائل الخاصة**: إرسال الرسائل، والتفاعل مع الرسائل
- **التفاعلات**: إضافة/إزالة تفاعلات emoji إلى المنشورات والرسائل الخاصة
- **الإعدادات**: إدارة أذونات plugin عبر أوامر الشرطة المائلة
تتوفر Skill تلقائيًا عند تثبيت plugin.
## القدرات
| الميزة | الحالة |
| --------------- | --------------------------------------- |
| الرسائل الخاصة | ✅ مدعومة |
| المجموعات/القنوات | ✅ مدعومة (مقيّدة بالإشارة افتراضيًا) |
| السلاسل | ✅ مدعومة (الردود التلقائية داخل السلسلة) |
| النص المنسق | ✅ يتم تحويل Markdown إلى تنسيق Tlon |
| الصور | ✅ يتم رفعها إلى تخزين Tlon |
| التفاعلات | ✅ عبر [Skill المضمّنة](#bundled-skill) |
| استطلاعات الرأي | ❌ غير مدعومة بعد |
| الأوامر الأصلية | ✅ مدعومة (للمالك فقط افتراضيًا) |
## استكشاف الأخطاء وإصلاحها
شغّل هذا التسلسل أولًا:
```bash
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
```
الإخفاقات الشائعة:
- **يتم تجاهل الرسائل الخاصة**: المرسل غير موجود في `dmAllowlist` ولم يتم تكوين `ownerShip` لتدفق الموافقة.
- **يتم تجاهل رسائل المجموعات**: لم يتم اكتشاف القناة أو أن المرسل غير مصرح له.
- **أخطاء الاتصال**: تحقق من أن عنوان URL الخاص بالسفينة قابل للوصول؛ فعّل `allowPrivateNetwork` للسفن المحلية.
- **أخطاء المصادقة**: تحقق من أن رمز تسجيل الدخول الحالي ما زال صالحًا (تتغير الرموز دوريًا).
## مرجع التكوين
التكوين الكامل: [التكوين](/gateway/configuration)
خيارات المزوّد:
- `channels.tlon.enabled`: تمكين/تعطيل بدء تشغيل القناة.
- `channels.tlon.ship`: اسم سفينة Urbit الخاصة بـ bot ‏(مثل `~sampel-palnet`).
- `channels.tlon.url`: عنوان URL الخاص بالسفينة (مثل `https://sampel-palnet.tlon.network`).
- `channels.tlon.code`: رمز تسجيل الدخول للسفينة.
- `channels.tlon.allowPrivateNetwork`: السماح بعناوين localhost/LAN ‏(تجاوز SSRF).
- `channels.tlon.ownerShip`: سفينة المالك لنظام الموافقة (مصرح لها دائمًا).
- `channels.tlon.dmAllowlist`: السفن المسموح لها بإرسال رسائل خاصة (فارغة = لا شيء).
- `channels.tlon.autoAcceptDmInvites`: القبول التلقائي للرسائل الخاصة من السفن الموجودة في قائمة السماح.
- `channels.tlon.autoAcceptGroupInvites`: القبول التلقائي لجميع دعوات المجموعات.
- `channels.tlon.autoDiscoverChannels`: الاكتشاف التلقائي لقنوات المجموعات (الافتراضي: true).
- `channels.tlon.groupChannels`: قنوات مثبتة يدويًا.
- `channels.tlon.defaultAuthorizedShips`: السفن المصرح لها في جميع القنوات.
- `channels.tlon.authorization.channelRules`: قواعد التفويض لكل قناة.
- `channels.tlon.showModelSignature`: إلحاق اسم النموذج بالرسائل.
## ملاحظات
- تتطلب الردود في المجموعات إشارة (مثل `~your-bot-ship`) للرد.
- الردود ضمن السلاسل: إذا كانت الرسالة الواردة داخل سلسلة، يرد OpenClaw داخل السلسلة.
- النص المنسق: يتم تحويل تنسيق Markdown ‏(الغامق، والمائل، والكود، والعناوين، والقوائم) إلى تنسيق Tlon الأصلي.
- الصور: يتم رفع عناوين URL إلى تخزين Tlon وتضمينها ككتل صور.
## ذو صلة
- [نظرة عامة على القنوات](/channels) — جميع القنوات المدعومة
- [الاقتران](/channels/pairing) — مصادقة الرسائل الخاصة وتدفق الاقتران
- [المجموعات](/channels/groups) — سلوك الدردشة الجماعية وضبط الإشارات
- [توجيه القنوات](/channels/channel-routing) — توجيه الجلسات للرسائل
- [الأمان](/gateway/security) — نموذج الوصول والتقوية

140
docs/ar/channels/troubleshooting.md Normal file
View File

@ -0,0 +1,140 @@
---
read_when:
- يشير نقل القناة إلى أنه متصل لكن الردود تفشل
- تحتاج إلى فحوصات خاصة بالقناة قبل الرجوع إلى وثائق المزوّد المتعمقة
summary: استكشاف سريع لمشكلات القنوات مع مؤشرات أعطال وإصلاحات خاصة بكل قناة
title: استكشاف مشكلات القنوات وإصلاحها
x-i18n:
generated_at: "2026-04-05T12:36:55Z"
model: gpt-5.4
provider: openai
source_hash: d45d8220505ea420d970b20bc66e65216c2d7024b5736db1936421ffc0676e1f
source_path: channels/troubleshooting.md
workflow: 15
---
# استكشاف مشكلات القنوات وإصلاحها
استخدم هذه الصفحة عندما تتصل قناة ما لكن يكون السلوك غير صحيح.
## تسلسل الأوامر
شغّل هذه الأوامر بالترتيب أولًا:
```bash
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe
```
الخط الأساسي السليم:
- `Runtime: running`
- `RPC probe: ok`
- يُظهر فحص القناة أن النقل متصل، وحيثما كان ذلك مدعومًا، `works` أو `audit ok`
## WhatsApp
### مؤشرات أعطال WhatsApp
| العرض | أسرع فحص | الإصلاح |
| ----------------------------- | -------------------------------------------------- | -------------------------------------------------------- |
| متصل لكن لا توجد ردود على الرسائل المباشرة | `openclaw pairing list whatsapp` | وافق على المرسل أو بدّل سياسة الرسائل المباشرة/قائمة السماح. |
| يتم تجاهل رسائل المجموعات | تحقّق من `requireMention` وأنماط الإشارة في الإعدادات | اذكر البوت أو خفف سياسة الإشارة لتلك المجموعة. |
| حلقات عشوائية من قطع الاتصال/إعادة تسجيل الدخول | `openclaw channels status --probe` + السجلات | سجّل الدخول مجددًا وتحقق من سلامة دليل بيانات الاعتماد. |
الاستكشاف الكامل للمشكلات: [/channels/whatsapp#troubleshooting](/channels/whatsapp#troubleshooting)
## Telegram
### مؤشرات أعطال Telegram
| العرض | أسرع فحص | الإصلاح |
| --------------------------------- | ---------------------------------------------- | ---------------------------------------------------------------------------- |
| `/start` لكن لا يوجد تدفق رد قابل للاستخدام | `openclaw pairing list telegram` | وافق على الاقتران أو غيّر سياسة الرسائل المباشرة. |
| البوت متصل لكن المجموعة تظل صامتة | تحقّق من متطلب الإشارة ووضع خصوصية البوت | عطّل وضع الخصوصية لرؤية رسائل المجموعة أو اذكر البوت. |
| فشل في الإرسال مع أخطاء شبكة | افحص السجلات بحثًا عن إخفاقات استدعاءات Telegram API | أصلح توجيه DNS/IPv6/proxy إلى `api.telegram.org`. |
| تم رفض `setMyCommands` عند بدء التشغيل | افحص السجلات بحثًا عن `BOT_COMMANDS_TOO_MUCH` | قلّل أوامر Telegram الأصلية أو أوامر plugin/Skills/الأوامر المخصصة أو عطّل القوائم الأصلية. |
| قمت بالترقية وأصبحت قائمة السماح تحظرك | `openclaw security audit` وقوائم السماح في الإعدادات | شغّل `openclaw doctor --fix` أو استبدل `@username` بمعرّفات المرسلين الرقمية. |
الاستكشاف الكامل للمشكلات: [/channels/telegram#troubleshooting](/channels/telegram#troubleshooting)
## Discord
### مؤشرات أعطال Discord
| العرض | أسرع فحص | الإصلاح |
| ----------------------------- | ------------------------------------- | ----------------------------------------------------------- |
| البوت متصل لكن لا يرد في الخوادم | `openclaw channels status --probe` | اسمح بالخادم/القناة وتحقق من صلاحية محتوى الرسائل. |
| يتم تجاهل رسائل المجموعات | تحقّق من السجلات بحثًا عن إسقاطات بوابة الإشارات | اذكر البوت أو اضبط `requireMention: false` للخادم/القناة. |
| ردود الرسائل المباشرة مفقودة | `openclaw pairing list discord` | وافق على اقتران الرسائل المباشرة أو عدّل سياسة الرسائل المباشرة. |
الاستكشاف الكامل للمشكلات: [/channels/discord#troubleshooting](/channels/discord#troubleshooting)
## Slack
### مؤشرات أعطال Slack
| العرض | أسرع فحص | الإصلاح |
| ------------------------------------ | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Socket mode متصل لكن لا توجد استجابات | `openclaw channels status --probe` | تحقّق من app token وbot token والنطاقات المطلوبة؛ وراقب `botTokenStatus` / `appTokenStatus = configured_unavailable` في الإعدادات المدعومة بـ SecretRef. |
| الرسائل المباشرة محظورة | `openclaw pairing list slack` | وافق على الاقتران أو خفف سياسة الرسائل المباشرة. |
| يتم تجاهل رسالة القناة | تحقّق من `groupPolicy` وقائمة السماح للقنوات | اسمح للقناة أو بدّل السياسة إلى `open`. |
الاستكشاف الكامل للمشكلات: [/channels/slack#troubleshooting](/channels/slack#troubleshooting)
## iMessage وBlueBubbles
### مؤشرات أعطال iMessage وBlueBubbles
| العرض | أسرع فحص | الإصلاح |
| ------------------------------ | ------------------------------------------------------------------- | ------------------------------------------------------ |
| لا توجد أحداث واردة | تحقّق من إمكانية الوصول إلى webhook/server وأذونات التطبيق | أصلح عنوان URL الخاص بـ webhook أو حالة خادم BlueBubbles. |
| يمكن الإرسال لكن لا يوجد استقبال على macOS | تحقّق من أذونات الخصوصية في macOS لأتمتة Messages | امنح أذونات TCC مجددًا وأعد تشغيل عملية القناة. |
| مرسل الرسائل المباشرة محظور | `openclaw pairing list imessage` أو `openclaw pairing list bluebubbles` | وافق على الاقتران أو حدّث قائمة السماح. |
الاستكشاف الكامل للمشكلات:
- [/channels/imessage#troubleshooting](/channels/imessage#troubleshooting)
- [/channels/bluebubbles#troubleshooting](/channels/bluebubbles#troubleshooting)
## Signal
### مؤشرات أعطال Signal
| العرض | أسرع فحص | الإصلاح |
| ----------------------------- | -------------------------------------- | --------------------------------------------------------- |
| يمكن الوصول إلى daemon لكن البوت صامت | `openclaw channels status --probe` | تحقّق من عنوان URL الخاص بـ daemon/الحساب في `signal-cli` ووضع الاستقبال. |
| الرسائل المباشرة محظورة | `openclaw pairing list signal` | وافق على المرسل أو عدّل سياسة الرسائل المباشرة. |
| لا يتم تشغيل الردود في المجموعات | تحقّق من قائمة السماح للمجموعة وأنماط الإشارة | أضف المرسل/المجموعة أو خفف البوابة. |
الاستكشاف الكامل للمشكلات: [/channels/signal#troubleshooting](/channels/signal#troubleshooting)
## QQ Bot
### مؤشرات أعطال QQ Bot
| العرض | أسرع فحص | الإصلاح |
| ----------------------------- | ----------------------------------------- | ----------------------------------------------------------------- |
| يرد البوت بعبارة "gone to Mars" | تحقّق من `appId` و`clientSecret` في الإعدادات | اضبط بيانات الاعتماد أو أعد تشغيل gateway. |
| لا توجد رسائل واردة | `openclaw channels status --probe` | تحقّق من بيانات الاعتماد في QQ Open Platform. |
| لم يتم تحويل الصوت إلى نص | تحقّق من إعدادات مزوّد STT | اضبط `channels.qqbot.stt` أو `tools.media.audio`. |
| الرسائل الاستباقية لا تصل | تحقّق من متطلبات التفاعل في منصة QQ | قد تحظر QQ الرسائل التي يبدأها البوت من دون تفاعل حديث. |
الاستكشاف الكامل للمشكلات: [/channels/qqbot#troubleshooting](/channels/qqbot#troubleshooting)
## Matrix
### مؤشرات أعطال Matrix
| العرض | أسرع فحص | الإصلاح |
| --------------------------------- | ---------------------------------------- | -------------------------------------------------------------------------- |
| تم تسجيل الدخول لكن يتم تجاهل رسائل الغرف | `openclaw channels status --probe` | تحقّق من `groupPolicy` وقائمة السماح للغرف وبوابة الإشارات. |
| لا تتم معالجة الرسائل المباشرة | `openclaw pairing list matrix` | وافق على المرسل أو عدّل سياسة الرسائل المباشرة. |
| الغرف المشفرة تفشل | `openclaw matrix verify status` | أعد التحقق من الجهاز، ثم افحص `openclaw matrix verify backup status`. |
| استعادة النسخة الاحتياطية معلقة/معطلة | `openclaw matrix verify backup status` | شغّل `openclaw matrix verify backup restore` أو أعد التشغيل باستخدام مفتاح استرداد. |
| يبدو bootstrap/cross-signing غير صحيح | `openclaw matrix verify bootstrap` | أصلح التخزين السري وcross-signing وحالة النسخ الاحتياطي في تمريرة واحدة. |
الإعداد الكامل والإعدادات: [Matrix](/channels/matrix)

401
docs/ar/channels/twitch.md Normal file
View File

@ -0,0 +1,401 @@
---
read_when:
- إعداد تكامل دردشة Twitch لـ OpenClaw
summary: تكوين وإعداد روبوت دردشة Twitch
title: Twitch
x-i18n:
generated_at: "2026-04-05T12:37:22Z"
model: gpt-5.4
provider: openai
source_hash: 47af9fb6edb1f462c5919850ee9d05e500a1914ddd0d64a41608fbe960e77cd6
source_path: channels/twitch.md
workflow: 15
---
# Twitch
دعم دردشة Twitch عبر اتصال IRC. يتصل OpenClaw كمستخدم Twitch (حساب روبوت) لاستقبال الرسائل وإرسالها في القنوات.
## Plugin مضمّن
يأتي Twitch كـ plugin مضمّن في إصدارات OpenClaw الحالية، لذا فإن
النسخ المجمعة العادية لا تحتاج إلى تثبيت منفصل.
إذا كنت تستخدم إصدارًا أقدم أو تثبيتًا مخصصًا لا يتضمن Twitch، فقم
بتثبيته يدويًا:
التثبيت عبر CLI (سجل npm):
```bash
openclaw plugins install @openclaw/twitch
```
نسخة محلية (عند التشغيل من مستودع git):
```bash
openclaw plugins install ./path/to/local/twitch-plugin
```
التفاصيل: [Plugins](/tools/plugin)
## إعداد سريع (للمبتدئين)
1. تأكد من أن plugin الخاص بـ Twitch متاح.
- تتضمنه إصدارات OpenClaw المجمعة الحالية بالفعل.
- يمكن لعمليات التثبيت الأقدم/المخصصة إضافته يدويًا بالأوامر أعلاه.
2. أنشئ حساب Twitch مخصصًا للروبوت (أو استخدم حسابًا موجودًا).
3. أنشئ بيانات الاعتماد: [Twitch Token Generator](https://twitchtokengenerator.com/)
- اختر **Bot Token**
- تحقق من تحديد النطاقين `chat:read` و`chat:write`
- انسخ **Client ID** و**Access Token**
4. اعثر على معرّف مستخدم Twitch الخاص بك: [https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/](https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/)
5. اضبط الرمز المميز:
- متغير البيئة: `OPENCLAW_TWITCH_ACCESS_TOKEN=...` (للحساب الافتراضي فقط)
- أو التكوين: `channels.twitch.accessToken`
- إذا تم تعيين الاثنين، تكون أولوية التكوين أعلى (والرجوع إلى env للحساب الافتراضي فقط).
6. ابدأ gateway.
**⚠️ مهم:** أضف عنصر تحكم في الوصول (`allowFrom` أو `allowedRoles`) لمنع المستخدمين غير المصرح لهم من تشغيل الروبوت. تكون `requireMention` مضبوطة افتراضيًا على `true`.
الحد الأدنى من التكوين:
```json5
{
channels: {
twitch: {
enabled: true,
username: "openclaw", // Bot's Twitch account
accessToken: "oauth:abc123...", // OAuth Access Token (or use OPENCLAW_TWITCH_ACCESS_TOKEN env var)
clientId: "xyz789...", // Client ID from Token Generator
channel: "vevisk", // Which Twitch channel's chat to join (required)
allowFrom: ["123456789"], // (recommended) Your Twitch user ID only - get it from https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/
},
},
}
```
## ما هو
- قناة Twitch مملوكة لـ Gateway.
- توجيه حتمي: تعود الردود دائمًا إلى Twitch.
- يُطابق كل حساب مفتاح جلسة معزولًا `agent:<agentId>:twitch:<accountName>`.
- `username` هو حساب الروبوت (الذي يصادق)، بينما `channel` هي غرفة الدردشة المطلوب الانضمام إليها.
## الإعداد (تفصيلي)
### إنشاء بيانات الاعتماد
استخدم [Twitch Token Generator](https://twitchtokengenerator.com/):
- اختر **Bot Token**
- تحقق من تحديد النطاقين `chat:read` و`chat:write`
- انسخ **Client ID** و**Access Token**
لا حاجة إلى تسجيل تطبيق يدويًا. تنتهي صلاحية الرموز المميزة بعد عدة ساعات.
### ضبط الروبوت
**متغير البيئة (للحساب الافتراضي فقط):**
```bash
OPENCLAW_TWITCH_ACCESS_TOKEN=oauth:abc123...
```
**أو التكوين:**
```json5
{
channels: {
twitch: {
enabled: true,
username: "openclaw",
accessToken: "oauth:abc123...",
clientId: "xyz789...",
channel: "vevisk",
},
},
}
```
إذا تم تعيين env والتكوين معًا، تكون أولوية التكوين أعلى.
### التحكم في الوصول (موصى به)
```json5
{
channels: {
twitch: {
allowFrom: ["123456789"], // (recommended) Your Twitch user ID only
},
},
}
```
فضّل `allowFrom` للحصول على قائمة سماح صارمة. استخدم `allowedRoles` بدلًا من ذلك إذا كنت تريد وصولًا قائمًا على الأدوار.
**الأدوار المتاحة:** `"moderator"` و`"owner"` و`"vip"` و`"subscriber"` و`"all"`.
**لماذا معرّفات المستخدمين؟** يمكن أن تتغير أسماء المستخدمين، مما يسمح بانتحال الهوية. أما معرّفات المستخدمين فهي دائمة.
اعثر على معرّف مستخدم Twitch الخاص بك: [https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/](https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/) (تحويل اسم مستخدم Twitch إلى معرّف)
## تحديث الرمز المميز (اختياري)
لا يمكن تحديث الرموز المميزة من [Twitch Token Generator](https://twitchtokengenerator.com/) تلقائيًا — أعد إنشاءها عند انتهاء صلاحيتها.
للحصول على تحديث تلقائي للرمز المميز، أنشئ تطبيق Twitch خاصًا بك في [Twitch Developer Console](https://dev.twitch.tv/console) وأضف إلى التكوين:
```json5
{
channels: {
twitch: {
clientSecret: "your_client_secret",
refreshToken: "your_refresh_token",
},
},
}
```
يحدّث الروبوت الرموز المميزة تلقائيًا قبل انتهاء صلاحيتها ويسجل أحداث التحديث.
## دعم الحسابات المتعددة
استخدم `channels.twitch.accounts` مع رموز مميزة لكل حساب. راجع [`gateway/configuration`](/gateway/configuration) للنمط المشترك.
مثال (حساب روبوت واحد في قناتين):
```json5
{
channels: {
twitch: {
accounts: {
channel1: {
username: "openclaw",
accessToken: "oauth:abc123...",
clientId: "xyz789...",
channel: "vevisk",
},
channel2: {
username: "openclaw",
accessToken: "oauth:def456...",
clientId: "uvw012...",
channel: "secondchannel",
},
},
},
},
}
```
**ملاحظة:** يحتاج كل حساب إلى رمزه المميز الخاص به (رمز واحد لكل قناة).
## التحكم في الوصول
### قيود قائمة على الأدوار
```json5
{
channels: {
twitch: {
accounts: {
default: {
allowedRoles: ["moderator", "vip"],
},
},
},
},
}
```
### قائمة سماح حسب معرّف المستخدم (الأكثر أمانًا)
```json5
{
channels: {
twitch: {
accounts: {
default: {
allowFrom: ["123456789", "987654321"],
},
},
},
},
}
```
### وصول قائم على الأدوار (بديل)
`allowFrom` هي قائمة سماح صارمة. عند تعيينها، يُسمح فقط لمعرّفات المستخدمين تلك.
إذا كنت تريد وصولًا قائمًا على الأدوار، فاترك `allowFrom` غير معيّنة واضبط `allowedRoles` بدلًا من ذلك:
```json5
{
channels: {
twitch: {
accounts: {
default: {
allowedRoles: ["moderator"],
},
},
},
},
}
```
### تعطيل شرط @mention
افتراضيًا، تكون `requireMention` هي `true`. لتعطيلها والرد على جميع الرسائل:
```json5
{
channels: {
twitch: {
accounts: {
default: {
requireMention: false,
},
},
},
},
}
```
## استكشاف الأخطاء وإصلاحها
أولًا، شغّل أوامر التشخيص:
```bash
openclaw doctor
openclaw channels status --probe
```
### الروبوت لا يرد على الرسائل
**تحقق من التحكم في الوصول:** تأكد من أن معرّف المستخدم الخاص بك موجود في `allowFrom`، أو أزل
`allowFrom` مؤقتًا واضبط `allowedRoles: ["all"]` للاختبار.
**تحقق من وجود الروبوت في القناة:** يجب أن ينضم الروبوت إلى القناة المحددة في `channel`.
### مشكلات الرمز المميز
**"Failed to connect" أو أخطاء المصادقة:**
- تحقق من أن `accessToken` هو قيمة OAuth access token (ويبدأ عادةً بالبادئة `oauth:`)
- تحقق من أن الرمز المميز يملك النطاقين `chat:read` و`chat:write`
- إذا كنت تستخدم تحديث الرمز المميز، فتأكد من تعيين `clientSecret` و`refreshToken`
### تحديث الرمز المميز لا يعمل
**تحقق من السجلات بحثًا عن أحداث التحديث:**
```
Using env token source for mybot
Access token refreshed for user 123456 (expires in 14400s)
```
إذا رأيت "token refresh disabled (no refresh token)":
- تأكد من توفير `clientSecret`
- تأكد من توفير `refreshToken`
## التكوين
**تكوين الحساب:**
- `username` - اسم مستخدم الروبوت
- `accessToken` - OAuth access token مع `chat:read` و`chat:write`
- `clientId` - Twitch Client ID (من Token Generator أو من تطبيقك)
- `channel` - القناة المطلوب الانضمام إليها (مطلوب)
- `enabled` - تمكين هذا الحساب (الافتراضي: `true`)
- `clientSecret` - اختياري: لتحديث الرمز المميز تلقائيًا
- `refreshToken` - اختياري: لتحديث الرمز المميز تلقائيًا
- `expiresIn` - انتهاء صلاحية الرمز المميز بالثواني
- `obtainmentTimestamp` - الطابع الزمني للحصول على الرمز المميز
- `allowFrom` - قائمة سماح معرّفات المستخدمين
- `allowedRoles` - التحكم في الوصول القائم على الأدوار (`"moderator" | "owner" | "vip" | "subscriber" | "all"`)
- `requireMention` - طلب @mention (الافتراضي: `true`)
**خيارات المزوّد:**
- `channels.twitch.enabled` - تمكين/تعطيل بدء تشغيل القناة
- `channels.twitch.username` - اسم مستخدم الروبوت (تكوين مبسط لحساب واحد)
- `channels.twitch.accessToken` - OAuth access token (تكوين مبسط لحساب واحد)
- `channels.twitch.clientId` - Twitch Client ID (تكوين مبسط لحساب واحد)
- `channels.twitch.channel` - القناة المطلوب الانضمام إليها (تكوين مبسط لحساب واحد)
- `channels.twitch.accounts.<accountName>` - تكوين متعدد الحسابات (جميع حقول الحساب أعلاه)
مثال كامل:
```json5
{
channels: {
twitch: {
enabled: true,
username: "openclaw",
accessToken: "oauth:abc123...",
clientId: "xyz789...",
channel: "vevisk",
clientSecret: "secret123...",
refreshToken: "refresh456...",
allowFrom: ["123456789"],
allowedRoles: ["moderator", "vip"],
accounts: {
default: {
username: "mybot",
accessToken: "oauth:abc123...",
clientId: "xyz789...",
channel: "your_channel",
enabled: true,
clientSecret: "secret123...",
refreshToken: "refresh456...",
expiresIn: 14400,
obtainmentTimestamp: 1706092800000,
allowFrom: ["123456789", "987654321"],
allowedRoles: ["moderator"],
},
},
},
},
}
```
## إجراءات الأداة
يمكن للوكيل استدعاء `twitch` مع الإجراء:
- `send` - إرسال رسالة إلى قناة
مثال:
```json5
{
action: "twitch",
params: {
message: "Hello Twitch!",
to: "#mychannel",
},
}
```
## السلامة والعمليات
- **تعامل مع الرموز المميزة كأنها كلمات مرور** - لا تُدرج الرموز المميزة في git أبدًا
- **استخدم تحديث الرمز المميز التلقائي** للروبوتات طويلة التشغيل
- **استخدم قوائم سماح معرّفات المستخدمين** بدلًا من أسماء المستخدمين للتحكم في الوصول
- **راقب السجلات** لأحداث تحديث الرموز المميزة وحالة الاتصال
- **قلّل نطاقات الرموز المميزة لأدنى حد** - اطلب فقط `chat:read` و`chat:write`
- **إذا علقت**: أعد تشغيل gateway بعد التأكد من عدم وجود عملية أخرى تملك الجلسة
## الحدود
- **500 حرف** لكل رسالة (مع تجزئة تلقائية عند حدود الكلمات)
- تتم إزالة Markdown قبل التجزئة
- لا يوجد تحديد لمعدل الطلبات (يستخدم حدود المعدل المضمنة في Twitch)
## ذو صلة
- [نظرة عامة على القنوات](/channels) — جميع القنوات المدعومة
- [Pairing](/channels/pairing) — مصادقة الرسائل المباشرة وتدفق pairing
- [المجموعات](/channels/groups) — سلوك الدردشة الجماعية وتقييد الإشارات
- [توجيه القنوات](/channels/channel-routing) — توجيه الجلسات للرسائل
- [الأمان](/gateway/security) — نموذج الوصول والتقوية

495
docs/ar/channels/whatsapp.md Normal file
View File

@ -0,0 +1,495 @@
---
read_when:
- العمل على سلوك قناة WhatsApp/web أو توجيه inbox
summary: دعم قناة WhatsApp، وعناصر التحكم في الوصول، وسلوك التسليم، والعمليات
title: WhatsApp
x-i18n:
generated_at: "2026-04-05T12:37:32Z"
model: gpt-5.4
provider: openai
source_hash: c16a468b3f47fdf7e4fc3fd745b5c49c7ccebb7af0e8c87c632b78b04c583e49
source_path: channels/whatsapp.md
workflow: 15
---
# WhatsApp (قناة Web)
الحالة: جاهزة للإنتاج عبر WhatsApp Web ‏(Baileys). يمتلك gateway الجلسة (الجلسات) المرتبطة.
## التثبيت (عند الطلب)
- يطلب كل من الإعداد التفاعلي (`openclaw onboard`) و`openclaw channels add --channel whatsapp`
تثبيت plugin WhatsApp في أول مرة تحددها فيها.
- يوفّر `openclaw channels login --channel whatsapp` أيضًا تدفق التثبيت عندما
لا يكون plugin موجودًا بعد.
- قناة التطوير + نسخة git محلية: تكون القيمة الافتراضية هي مسار plugin المحلي.
- Stable/Beta: القيمة الافتراضية هي حزمة npm ‏`@openclaw/whatsapp`.
يبقى التثبيت اليدوي متاحًا:
```bash
openclaw plugins install @openclaw/whatsapp
```
<CardGroup cols={3}>
<Card title="الاقتران" icon="link" href="/channels/pairing">
سياسة الرسائل الخاصة الافتراضية هي الاقتران للمرسلين غير المعروفين.
</Card>
<Card title="استكشاف أخطاء القنوات وإصلاحها" icon="wrench" href="/channels/troubleshooting">
أدوات التشخيص وخطط الإصلاح عبر القنوات.
</Card>
<Card title="تكوين Gateway" icon="settings" href="/gateway/configuration">
أنماط وأمثلة تكوين القنوات الكاملة.
</Card>
</CardGroup>
## الإعداد السريع
<Steps>
<Step title="تكوين سياسة الوصول إلى WhatsApp">
```json5
{
channels: {
whatsapp: {
dmPolicy: "pairing",
allowFrom: ["+15551234567"],
groupPolicy: "allowlist",
groupAllowFrom: ["+15551234567"],
},
},
}
```
</Step>
<Step title="ربط WhatsApp ‏(QR)">
```bash
openclaw channels login --channel whatsapp
```
لحساب محدد:
```bash
openclaw channels login --channel whatsapp --account work
```
</Step>
<Step title="بدء تشغيل gateway">
```bash
openclaw gateway
```
</Step>
<Step title="الموافقة على أول طلب اقتران (إذا كنت تستخدم وضع الاقتران)">
```bash
openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>
```
تنتهي صلاحية طلبات الاقتران بعد ساعة واحدة. الحد الأقصى للطلبات المعلقة هو 3 لكل قناة.
</Step>
</Steps>
<Note>
يوصي OpenClaw بتشغيل WhatsApp على رقم منفصل كلما أمكن ذلك. (تم تحسين بيانات تعريف القناة وتدفق الإعداد لهذا الإعداد، لكن الإعدادات التي تستخدم الرقم الشخصي مدعومة أيضًا.)
</Note>
## أنماط النشر
<AccordionGroup>
<Accordion title="رقم مخصص (موصى به)">
هذا هو وضع التشغيل الأنظف:
- هوية WhatsApp منفصلة لـ OpenClaw
- حدود أوضح لقوائم السماح بالرسائل الخاصة والتوجيه
- احتمال أقل لحدوث ارتباك في الدردشة الذاتية
نمط السياسة الأدنى:
```json5
{
channels: {
whatsapp: {
dmPolicy: "allowlist",
allowFrom: ["+15551234567"],
},
},
}
```
</Accordion>
<Accordion title="بديل الرقم الشخصي">
يدعم الإعداد التفاعلي وضع الرقم الشخصي ويكتب خط أساس مناسبًا للدردشة الذاتية:
- `dmPolicy: "allowlist"`
- تتضمن `allowFrom` رقمك الشخصي
- `selfChatMode: true`
في وقت التشغيل، تعتمد وسائل الحماية من الدردشة الذاتية على الرقم الذاتي المرتبط و`allowFrom`.
</Accordion>
<Accordion title="نطاق قناة WhatsApp Web فقط">
قناة منصة المراسلة في بنية قنوات OpenClaw الحالية تستند إلى WhatsApp Web ‏(`Baileys`).
لا توجد قناة مراسلة WhatsApp منفصلة عبر Twilio ضمن سجل قنوات الدردشة المدمج.
</Accordion>
</AccordionGroup>
## نموذج وقت التشغيل
- يمتلك gateway مقبس WhatsApp وحلقة إعادة الاتصال.
- تتطلب عمليات الإرسال الصادرة وجود مستمع WhatsApp نشط للحساب الهدف.
- يتم تجاهل محادثات الحالة والبث (`@status` و`@broadcast`).
- تستخدم المحادثات المباشرة قواعد جلسات الرسائل الخاصة (`session.dmScope`؛ القيمة الافتراضية `main` تؤدي إلى طي الرسائل الخاصة ضمن الجلسة الرئيسية للوكيل).
- تكون جلسات المجموعات معزولة (`agent:<agentId>:whatsapp:group:<jid>`).
## التحكم في الوصول والتفعيل
<Tabs>
<Tab title="سياسة الرسائل الخاصة">
يتحكم `channels.whatsapp.dmPolicy` في الوصول إلى الدردشة المباشرة:
- `pairing` (الافتراضي)
- `allowlist`
- `open` (يتطلب أن تتضمن `allowFrom` القيمة `"*"`)
- `disabled`
تقبل `allowFrom` أرقامًا بنمط E.164 (ويتم تطبيعها داخليًا).
تجاوز الحسابات المتعددة: تكون `channels.whatsapp.accounts.<id>.dmPolicy` (و`allowFrom`) لها الأولوية على القيم الافتراضية على مستوى القناة لذلك الحساب.
تفاصيل سلوك وقت التشغيل:
- يتم الاحتفاظ بعمليات الاقتران في مخزن السماح الخاص بالقناة ودمجها مع `allowFrom` المكوّنة
- إذا لم يتم تكوين أي قائمة سماح، يُسمح بالرقم الذاتي المرتبط افتراضيًا
- لا يتم أبدًا إقران الرسائل الخاصة الصادرة `fromMe` تلقائيًا
</Tab>
<Tab title="سياسة المجموعات + قوائم السماح">
يتكون الوصول إلى المجموعات من طبقتين:
1. **قائمة سماح عضوية المجموعة** (`channels.whatsapp.groups`)
- إذا تم حذف `groups`، تكون كل المجموعات مؤهلة
- إذا وُجدت `groups`، فإنها تعمل كقائمة سماح للمجموعات (مع السماح بـ `"*"`)
2. **سياسة مرسل المجموعة** (`channels.whatsapp.groupPolicy` + `groupAllowFrom`)
- `open`: يتم تجاوز قائمة سماح المرسلين
- `allowlist`: يجب أن يطابق المرسل `groupAllowFrom` (أو `*`)
- `disabled`: حظر كل الرسائل الواردة من المجموعات
بديل قائمة سماح المرسلين:
- إذا لم يتم تعيين `groupAllowFrom`، يعود وقت التشغيل إلى `allowFrom` عند توفرها
- يتم تقييم قوائم سماح المرسلين قبل تفعيل الإشارة/الرد
ملاحظة: إذا لم توجد كتلة `channels.whatsapp` إطلاقًا، فإن بديل سياسة المجموعات في وقت التشغيل يكون `allowlist` (مع سجل تحذير)، حتى لو كانت `channels.defaults.groupPolicy` معيّنة.
</Tab>
<Tab title="الإشارات + /activation">
تتطلب الردود في المجموعات الإشارة افتراضيًا.
يتضمن اكتشاف الإشارة:
- إشارات WhatsApp الصريحة لهوية bot
- أنماط regex المكوّنة للإشارة (`agents.list[].groupChat.mentionPatterns`، والبديل `messages.groupChat.mentionPatterns`)
- اكتشاف الرد الضمني على bot ‏(يطابق مرسل الرد هوية bot)
ملاحظة أمنية:
- الاقتباس/الرد يفي فقط بضبط الإشارة؛ ولا يمنح تفويض المرسل
- مع `groupPolicy: "allowlist"`، يظل المرسلون غير المدرجين في قائمة السماح محظورين حتى إذا ردوا على رسالة من مستخدم مدرج في قائمة السماح
أمر التفعيل على مستوى الجلسة:
- `/activation mention`
- `/activation always`
يقوم `activation` بتحديث حالة الجلسة (وليس التكوين العام). وهو مقيّد بالمالك.
</Tab>
</Tabs>
## سلوك الرقم الشخصي والدردشة الذاتية
عندما يكون الرقم الذاتي المرتبط موجودًا أيضًا في `allowFrom`، يتم تفعيل ضمانات الدردشة الذاتية في WhatsApp:
- تخطي إيصالات القراءة في أدوار الدردشة الذاتية
- تجاهل سلوك التشغيل التلقائي لإشارة JID الذي قد يؤدي بخلاف ذلك إلى تنبيهك لنفسك
- إذا لم تكن `messages.responsePrefix` معيّنة، فإن ردود الدردشة الذاتية تستخدم افتراضيًا `[{identity.name}]` أو `[openclaw]`
## تطبيع الرسائل والسياق
<AccordionGroup>
<Accordion title="الغلاف الوارد + سياق الرد">
تُغلَّف رسائل WhatsApp الواردة في الغلاف الوارد المشترك.
إذا وُجد رد مقتبس، يُضاف السياق بهذا الشكل:
```text
[Replying to <sender> id:<stanzaId>]
<quoted body or media placeholder>
[/Replying]
```
كما تتم تعبئة حقول بيانات تعريف الرد عند توفرها (`ReplyToId` و`ReplyToBody` و`ReplyToSender` وJID/E.164 الخاص بالمرسل).
</Accordion>
<Accordion title="عناصر الوسائط النائبة واستخراج الموقع/جهة الاتصال">
يتم تطبيع الرسائل الواردة التي تحتوي على وسائط فقط باستخدام عناصر نائبة مثل:
- `<media:image>`
- `<media:video>`
- `<media:audio>`
- `<media:document>`
- `<media:sticker>`
يتم تطبيع حمولات الموقع وجهات الاتصال إلى سياق نصي قبل التوجيه.
</Accordion>
<Accordion title="حقن سجل المجموعات المعلق">
بالنسبة إلى المجموعات، يمكن تخزين الرسائل غير المعالجة مؤقتًا وحقنها كسياق عندما يتم تشغيل bot أخيرًا.
- الحد الافتراضي: `50`
- التكوين: `channels.whatsapp.historyLimit`
- البديل: `messages.groupChat.historyLimit`
- `0` يعطّل الميزة
علامات الحقن:
- `[Chat messages since your last reply - for context]`
- `[Current message - respond to this]`
</Accordion>
<Accordion title="إيصالات القراءة">
تكون إيصالات القراءة ممكّنة افتراضيًا لرسائل WhatsApp الواردة المقبولة.
التعطيل عالميًا:
```json5
{
channels: {
whatsapp: {
sendReadReceipts: false,
},
},
}
```
تجاوز لكل حساب:
```json5
{
channels: {
whatsapp: {
accounts: {
work: {
sendReadReceipts: false,
},
},
},
},
}
```
تتخطى أدوار الدردشة الذاتية إيصالات القراءة حتى عند تمكينها عالميًا.
</Accordion>
</AccordionGroup>
## التسليم والتجزئة والوسائط
<AccordionGroup>
<Accordion title="تجزئة النص">
- حد التجزئة الافتراضي: `channels.whatsapp.textChunkLimit = 4000`
- `channels.whatsapp.chunkMode = "length" | "newline"`
- يفضل وضع `newline` حدود الفقرات (الأسطر الفارغة)، ثم يعود إلى التجزئة الآمنة حسب الطول
</Accordion>
<Accordion title="سلوك الوسائط الصادرة">
- يدعم حمولات الصور والفيديو والصوت (ملاحظة صوتية PTT) والمستندات
- تتم إعادة كتابة `audio/ogg` إلى `audio/ogg; codecs=opus` للتوافق مع الملاحظات الصوتية
- يتم دعم تشغيل GIF المتحرك عبر `gifPlayback: true` عند إرسال الفيديو
- تُطبَّق التسميات التوضيحية على أول عنصر وسائط عند إرسال حمولات رد متعددة الوسائط
- يمكن أن يكون مصدر الوسائط هو HTTP(S) أو `file://` أو مسارات محلية
</Accordion>
<Accordion title="حدود حجم الوسائط وسلوك البديل">
- حد حفظ الوسائط الواردة: `channels.whatsapp.mediaMaxMb` (الافتراضي `50`)
- حد إرسال الوسائط الصادرة: `channels.whatsapp.mediaMaxMb` (الافتراضي `50`)
- تستخدم تجاوزات كل حساب `channels.whatsapp.accounts.<accountId>.mediaMaxMb`
- يتم تحسين الصور تلقائيًا (تغيير الحجم/اجتياز الجودة) لتلائم الحدود
- عند فشل إرسال الوسائط، يرسل البديل الخاص بأول عنصر تحذيرًا نصيًا بدلًا من إسقاط الرد بصمت
</Accordion>
</AccordionGroup>
## مستوى التفاعل
يتحكم `channels.whatsapp.reactionLevel` في مدى استخدام الوكيل لتفاعلات emoji على WhatsApp:
| المستوى | تفاعلات الإقرار | التفاعلات التي يبدأها الوكيل | الوصف |
| ------------- | --------------- | ---------------------------- | ------------------------------------------------ |
| `"off"` | لا | لا | لا توجد تفاعلات إطلاقًا |
| `"ack"` | نعم | لا | تفاعلات الإقرار فقط (إيصال ما قبل الرد) |
| `"minimal"` | نعم | نعم (بشكل محافظ) | تفاعلات الإقرار + تفاعلات الوكيل مع توجيه محافظ |
| `"extensive"` | نعم | نعم (مشجعة) | تفاعلات الإقرار + تفاعلات الوكيل مع توجيه مشجع |
الافتراضي: `"minimal"`.
تستخدم تجاوزات كل حساب `channels.whatsapp.accounts.<id>.reactionLevel`.
```json5
{
channels: {
whatsapp: {
reactionLevel: "ack",
},
},
}
```
## تفاعلات الإقرار
يدعم WhatsApp تفاعلات الإقرار الفورية عند الاستلام الوارد عبر `channels.whatsapp.ackReaction`.
تخضع تفاعلات الإقرار إلى `reactionLevel` — ويتم إخفاؤها عندما تكون قيمة `reactionLevel` هي `"off"`.
```json5
{
channels: {
whatsapp: {
ackReaction: {
emoji: "👀",
direct: true,
group: "mentions", // always | mentions | never
},
},
},
}
```
ملاحظات السلوك:
- تُرسَل فورًا بعد قبول الرسالة الواردة (قبل الرد)
- يتم تسجيل الإخفاقات لكنها لا تمنع تسليم الرد العادي
- في وضع المجموعة `mentions`، يتم التفاعل في الأدوار التي يتم تشغيلها بالإشارة؛ ويعمل تفعيل المجموعة `always` كتجاوز لهذا الفحص
- يستخدم WhatsApp الإعداد `channels.whatsapp.ackReaction` (ولا يُستخدم هنا الإعداد القديم `messages.ackReaction`)
## الحسابات المتعددة وبيانات الاعتماد
<AccordionGroup>
<Accordion title="اختيار الحساب والقيم الافتراضية">
- تأتي معرّفات الحسابات من `channels.whatsapp.accounts`
- اختيار الحساب الافتراضي: `default` إذا كان موجودًا، وإلا أول معرّف حساب مكوَّن (مرتب)
- يتم تطبيع معرّفات الحسابات داخليًا لأغراض البحث
</Accordion>
<Accordion title="مسارات بيانات الاعتماد والتوافق مع الأنظمة القديمة">
- مسار المصادقة الحالي: `~/.openclaw/credentials/whatsapp/<accountId>/creds.json`
- ملف النسخة الاحتياطية: `creds.json.bak`
- ما زالت مصادقة النظام القديم الافتراضية في `~/.openclaw/credentials/` معرّفًا بها/تُنقل لتدفقات الحساب الافتراضي
</Accordion>
<Accordion title="سلوك تسجيل الخروج">
يؤدي `openclaw channels logout --channel whatsapp [--account <id>]` إلى مسح حالة مصادقة WhatsApp لذلك الحساب.
في أدلة المصادقة القديمة، يتم الاحتفاظ بـ `oauth.json` بينما تتم إزالة ملفات مصادقة Baileys.
</Accordion>
</AccordionGroup>
## الأدوات والإجراءات وعمليات كتابة التكوين
- يتضمن دعم أدوات الوكيل إجراء تفاعل WhatsApp ‏(`react`).
- بوابات الإجراءات:
- `channels.whatsapp.actions.reactions`
- `channels.whatsapp.actions.polls`
- تكون عمليات كتابة التكوين التي تبدأها القناة ممكّنة افتراضيًا (عطّلها عبر `channels.whatsapp.configWrites=false`).
## استكشاف الأخطاء وإصلاحها
<AccordionGroup>
<Accordion title="غير مرتبط (يلزم QR)">
العَرَض: تشير حالة القناة إلى أنها غير مرتبطة.
الإصلاح:
```bash
openclaw channels login --channel whatsapp
openclaw channels status
```
</Accordion>
<Accordion title="مرتبط لكن غير متصل / حلقة إعادة اتصال">
العَرَض: حساب مرتبط مع انقطاعات متكررة أو محاولات إعادة اتصال.
الإصلاح:
```bash
openclaw doctor
openclaw logs --follow
```
إذا لزم الأمر، أعد الربط باستخدام `channels login`.
</Accordion>
<Accordion title="لا يوجد مستمع نشط عند الإرسال">
تفشل عمليات الإرسال الصادرة بسرعة عندما لا يوجد مستمع gateway نشط للحساب الهدف.
تأكد من أن gateway يعمل وأن الحساب مرتبط.
</Accordion>
<Accordion title="يتم تجاهل رسائل المجموعات بشكل غير متوقع">
تحقق بالترتيب التالي:
- `groupPolicy`
- `groupAllowFrom` / `allowFrom`
- إدخالات قائمة سماح `groups`
- ضبط الإشارة (`requireMention` + أنماط الإشارة)
- المفاتيح المكررة في `openclaw.json` ‏(JSON5): تتجاوز الإدخالات اللاحقة الإدخالات السابقة، لذا احتفظ بقيمة `groupPolicy` واحدة لكل نطاق
</Accordion>
<Accordion title="تحذير وقت تشغيل Bun">
يجب أن يستخدم وقت تشغيل WhatsApp gateway بيئة Node. تُصنَّف Bun على أنها غير متوافقة مع التشغيل المستقر لـ WhatsApp/Telegram gateway.
</Accordion>
</AccordionGroup>
## مؤشرات مرجع التكوين
المرجع الأساسي:
- [مرجع التكوين - WhatsApp](/gateway/configuration-reference#whatsapp)
حقول WhatsApp عالية الأهمية:
- الوصول: `dmPolicy` و`allowFrom` و`groupPolicy` و`groupAllowFrom` و`groups`
- التسليم: `textChunkLimit` و`chunkMode` و`mediaMaxMb` و`sendReadReceipts` و`ackReaction` و`reactionLevel`
- الحسابات المتعددة: `accounts.<id>.enabled` و`accounts.<id>.authDir` والتجاوزات على مستوى الحساب
- العمليات: `configWrites` و`debounceMs` و`web.enabled` و`web.heartbeatSeconds` و`web.reconnect.*`
- سلوك الجلسة: `session.dmScope` و`historyLimit` و`dmHistoryLimit` و`dms.<id>.historyLimit`
## ذو صلة
- [الاقتران](/channels/pairing)
- [المجموعات](/channels/groups)
- [الأمان](/gateway/security)
- [توجيه القنوات](/channels/channel-routing)
- [التوجيه متعدد الوكلاء](/concepts/multi-agent)
- [استكشاف الأخطاء وإصلاحها](/channels/troubleshooting)

261
docs/ar/channels/zalo.md Normal file
View File

@ -0,0 +1,261 @@
---
read_when:
- عند العمل على ميزات Zalo أو webhooks
summary: حالة دعم بوت Zalo، والإمكانات، والإعدادات
title: Zalo
x-i18n:
generated_at: "2026-04-05T12:37:41Z"
model: gpt-5.4
provider: openai
source_hash: ab94642ba28e79605b67586af8f71c18bc10e0af60343a7df508e6823b6f4119
source_path: channels/zalo.md
workflow: 15
---
# Zalo (Bot API)
الحالة: تجريبي. الرسائل الخاصة مدعومة. يعكس قسم [الإمكانات](#capabilities) أدناه سلوك بوتات Marketplace الحالي.
## الإضافة المضمنة
يأتي Zalo كإضافة مضمنة في إصدارات OpenClaw الحالية، لذلك لا تحتاج
البُنى المجمعة العادية إلى تثبيت منفصل.
إذا كنت تستخدم إصدارًا أقدم أو تثبيتًا مخصصًا يستبعد Zalo، فقم بتثبيته
يدويًا:
- التثبيت عبر CLI: `openclaw plugins install @openclaw/zalo`
- أو من نسخة مصدر محلية: `openclaw plugins install ./path/to/local/zalo-plugin`
- التفاصيل: [الإضافات](/tools/plugin)
## إعداد سريع (للمبتدئين)
1. تأكد من أن إضافة Zalo متوفرة.
- تتضمنها بالفعل إصدارات OpenClaw المجمعة الحالية.
- يمكن لعمليات التثبيت القديمة/المخصصة إضافتها يدويًا باستخدام الأوامر أعلاه.
2. اضبط الرمز المميز:
- Env: `ZALO_BOT_TOKEN=...`
- أو في الإعدادات: `channels.zalo.accounts.default.botToken: "..."`.
3. أعد تشغيل البوابة (أو أكمل الإعداد).
4. يكون الوصول عبر الرسائل الخاصة في وضع الاقتران افتراضيًا؛ وافق على رمز الاقتران عند أول تواصل.
الحد الأدنى من الإعدادات:
```json5
{
channels: {
zalo: {
enabled: true,
accounts: {
default: {
botToken: "12345689:abc-xyz",
dmPolicy: "pairing",
},
},
},
},
}
```
## ما هو
Zalo هو تطبيق مراسلة يركز على فيتنام؛ وتتيح Bot API الخاصة به للبوابة تشغيل بوت للمحادثات الفردية 1:1.
وهو مناسب جيدًا للدعم أو الإشعارات عندما تريد توجيهًا حتميًا للعودة إلى Zalo.
تعكس هذه الصفحة سلوك OpenClaw الحالي بالنسبة إلى **بوتات Zalo Bot Creator / Marketplace**.
أما **بوتات Zalo Official Account (OA)** فهي سطح منتج مختلف في Zalo وقد تتصرف بشكل مختلف.
- قناة Zalo Bot API تملكها البوابة.
- توجيه حتمي: تعود الردود إلى Zalo؛ ولا يختار النموذج القنوات.
- تشارك الرسائل الخاصة الجلسة الرئيسية للوكيل.
- يوضح قسم [الإمكانات](#capabilities) أدناه الدعم الحالي لبوتات Marketplace.
## الإعداد (المسار السريع)
### 1) إنشاء رمز بوت مميز (Zalo Bot Platform)
1. انتقل إلى [https://bot.zaloplatforms.com](https://bot.zaloplatforms.com) وسجّل الدخول.
2. أنشئ بوتًا جديدًا واضبط إعداداته.
3. انسخ الرمز المميز الكامل للبوت (عادةً `numeric_id:secret`). بالنسبة إلى بوتات Marketplace، قد يظهر رمز وقت التشغيل القابل للاستخدام في رسالة الترحيب الخاصة بالبوت بعد الإنشاء.
### 2) إعداد الرمز المميز (env أو config)
مثال:
```json5
{
channels: {
zalo: {
enabled: true,
accounts: {
default: {
botToken: "12345689:abc-xyz",
dmPolicy: "pairing",
},
},
},
},
}
```
إذا انتقلت لاحقًا إلى سطح بوت Zalo تتوفر فيه المجموعات، فيمكنك إضافة إعدادات خاصة بالمجموعات مثل `groupPolicy` و`groupAllowFrom` بشكل صريح. بالنسبة إلى سلوك بوتات Marketplace الحالي، راجع [الإمكانات](#capabilities).
خيار Env: `ZALO_BOT_TOKEN=...` (يعمل للحساب الافتراضي فقط).
دعم الحسابات المتعددة: استخدم `channels.zalo.accounts` مع رموز مميزة لكل حساب و`name` اختياري.
3. أعد تشغيل البوابة. يبدأ Zalo عند حل الرمز المميز (من env أو config).
4. يكون الوصول عبر الرسائل الخاصة مضبوطًا افتراضيًا على الاقتران. وافق على الرمز عند أول تواصل مع البوت.
## كيف يعمل (السلوك)
- تُطبَّع الرسائل الواردة إلى غلاف القناة المشترك مع عناصر نائبة للوسائط.
- تُوجَّه الردود دائمًا إلى دردشة Zalo نفسها.
- يستخدم long-polling افتراضيًا؛ ويتوفر وضع webhook مع `channels.zalo.webhookUrl`.
## الحدود
- يُجزّأ النص الصادر إلى 2000 حرف (حد Zalo API).
- تُقيَّد تنزيلات/تحميلات الوسائط بواسطة `channels.zalo.mediaMaxMb` (الافتراضي 5).
- يكون البث محظورًا افتراضيًا لأن حد 2000 حرف يجعل البث أقل فائدة.
## التحكم في الوصول (الرسائل الخاصة)
### الوصول عبر الرسائل الخاصة
- الافتراضي: `channels.zalo.dmPolicy = "pairing"`. يتلقى المرسلون غير المعروفين رمز اقتران؛ ويتم تجاهل الرسائل حتى تتم الموافقة عليها (تنتهي صلاحية الرموز بعد ساعة واحدة).
- الموافقة عبر:
- `openclaw pairing list zalo`
- `openclaw pairing approve zalo <CODE>`
- الاقتران هو آلية تبادل الرموز الافتراضية. التفاصيل: [الاقتران](/channels/pairing)
- يقبل `channels.zalo.allowFrom` معرّفات مستخدمين رقمية (لا يتوفر بحث باسم المستخدم).
## التحكم في الوصول (المجموعات)
بالنسبة إلى **بوتات Zalo Bot Creator / Marketplace**، لم يكن دعم المجموعات متاحًا عمليًا لأن البوت لم يكن بالإمكان إضافته إلى مجموعة أصلًا.
هذا يعني أن مفاتيح الإعدادات المتعلقة بالمجموعات أدناه موجودة في المخطط، لكنها لم تكن قابلة للاستخدام مع بوتات Marketplace:
- يتحكم `channels.zalo.groupPolicy` في معالجة الرسائل الواردة من المجموعات: `open | allowlist | disabled`.
- يقيّد `channels.zalo.groupAllowFrom` معرّفات المرسلين الذين يمكنهم تشغيل البوت في المجموعات.
- إذا لم يتم تعيين `groupAllowFrom`، فيرجع Zalo إلى `allowFrom` لفحوصات المرسلين.
- ملاحظة وقت التشغيل: إذا كان `channels.zalo` مفقودًا بالكامل، فإن وقت التشغيل لا يزال يرجع إلى `groupPolicy="allowlist"` من أجل الأمان.
قيم سياسة المجموعات (عندما يكون الوصول إلى المجموعات متاحًا على سطح البوت لديك) هي:
- `groupPolicy: "disabled"` — يحظر جميع رسائل المجموعات.
- `groupPolicy: "open"` — يسمح لأي عضو في المجموعة (مع تقييد بالإشارة).
- `groupPolicy: "allowlist"` — افتراضي مغلق الفشل؛ لا يتم قبول سوى المرسلين المسموح لهم.
إذا كنت تستخدم سطح منتج مختلفًا لبوت Zalo وقد تحققت من أن سلوك المجموعات يعمل، فوثّق ذلك بشكل منفصل بدلًا من افتراض أنه يطابق تدفق بوتات Marketplace.
## long-polling مقابل webhook
- الافتراضي: long-polling (لا يلزم عنوان URL عام).
- وضع webhook: اضبط `channels.zalo.webhookUrl` و`channels.zalo.webhookSecret`.
- يجب أن يكون سر webhook بين 8 و256 حرفًا.
- يجب أن يستخدم عنوان URL الخاص بـ webhook بروتوكول HTTPS.
- يرسل Zalo الأحداث مع ترويسة `X-Bot-Api-Secret-Token` للتحقق.
- يتولى HTTP الخاص بالبوابة معالجة طلبات webhook عند `channels.zalo.webhookPath` (الافتراضي هو مسار عنوان URL الخاص بـ webhook).
- يجب أن تستخدم الطلبات `Content-Type: application/json` (أو أنواع وسائط `+json`).
- يتم تجاهل الأحداث المكررة (`event_name + message_id`) خلال نافذة إعادة تشغيل قصيرة.
- يتم تطبيق تحديد معدل على الاندفاعات المرورية لكل مسار/مصدر وقد تعيد HTTP 429.
**ملاحظة:** `getUpdates` (الاستطلاع) وwebhook متنافيان وفقًا لوثائق Zalo API.
## أنواع الرسائل المدعومة
للحصول على لقطة سريعة للدعم، راجع [الإمكانات](#capabilities). تضيف الملاحظات أدناه تفاصيل حيث يحتاج السلوك إلى سياق إضافي.
- **الرسائل النصية**: دعم كامل مع تجزئة عند 2000 حرف.
- **عناوين URL العادية في النص**: تتصرف مثل الإدخال النصي العادي.
- **معاينات الروابط / بطاقات الروابط الغنية**: راجع حالة بوتات Marketplace في [الإمكانات](#capabilities)؛ إذ لم تكن تستثير ردًا بشكل موثوق.
- **رسائل الصور**: راجع حالة بوتات Marketplace في [الإمكانات](#capabilities)؛ كانت معالجة الصور الواردة غير موثوقة (مؤشر كتابة من دون رد نهائي).
- **الملصقات**: راجع حالة بوتات Marketplace في [الإمكانات](#capabilities).
- **الملاحظات الصوتية / الملفات الصوتية / الفيديو / مرفقات الملفات العامة**: راجع حالة بوتات Marketplace في [الإمكانات](#capabilities).
- **الأنواع غير المدعومة**: يتم تسجيلها (مثل الرسائل الواردة من المستخدمين المحميين).
## الإمكانات
يلخص هذا الجدول سلوك **بوتات Zalo Bot Creator / Marketplace** الحالي في OpenClaw.
| الميزة | الحالة |
| ------ | ------ |
| الرسائل المباشرة | ✅ مدعومة |
| المجموعات | ❌ غير متاحة لبوتات Marketplace |
| الوسائط (الصور الواردة) | ⚠️ محدودة / تحقّق في بيئتك |
| الوسائط (الصور الصادرة) | ⚠️ لم يُعاد اختبارها لبوتات Marketplace |
| عناوين URL العادية في النص | ✅ مدعومة |
| معاينات الروابط | ⚠️ غير موثوقة لبوتات Marketplace |
| التفاعلات | ❌ غير مدعومة |
| الملصقات | ⚠️ لا يوجد رد من الوكيل لبوتات Marketplace |
| الملاحظات الصوتية / الصوت / الفيديو | ⚠️ لا يوجد رد من الوكيل لبوتات Marketplace |
| مرفقات الملفات | ⚠️ لا يوجد رد من الوكيل لبوتات Marketplace |
| السلاسل | ❌ غير مدعومة |
| Polls | ❌ غير مدعومة |
| الأوامر الأصلية | ❌ غير مدعومة |
| البث | ⚠️ محظور (حد 2000 حرف) |
## أهداف التسليم (CLI/cron)
- استخدم معرّف دردشة كهدف.
- مثال: `openclaw message send --channel zalo --target 123456789 --message "hi"`.
## استكشاف الأخطاء وإصلاحها
**البوت لا يرد:**
- تحقّق من أن الرمز المميز صالح: `openclaw channels status --probe`
- تحقّق من أن المرسل معتمد (عبر الاقتران أو `allowFrom`)
- تحقّق من سجلات البوابة: `openclaw logs --follow`
**webhook لا يستقبل الأحداث:**
- تأكد من أن عنوان URL الخاص بـ webhook يستخدم HTTPS
- تحقّق من أن الرمز السري يتكون من 8 إلى 256 حرفًا
- أكّد أن نقطة نهاية HTTP الخاصة بالبوابة قابلة للوصول على المسار المهيأ
- تحقّق من أن استطلاع `getUpdates` لا يعمل (فهما متنافيان)
## مرجع الإعدادات (Zalo)
الإعدادات الكاملة: [الإعدادات](/gateway/configuration)
المفاتيح المسطحة ذات المستوى الأعلى (`channels.zalo.botToken` و`channels.zalo.dmPolicy` وما شابه) هي صيغة مختصرة قديمة لحساب واحد. فضّل `channels.zalo.accounts.<id>.*` في الإعدادات الجديدة. لا يزال كلا الشكلين موثقًا هنا لأنهما موجودان في المخطط.
خيارات الموفّر:
- `channels.zalo.enabled`: تمكين/تعطيل بدء تشغيل القناة.
- `channels.zalo.botToken`: رمز البوت المميز من Zalo Bot Platform.
- `channels.zalo.tokenFile`: قراءة الرمز المميز من مسار ملف عادي. يتم رفض الروابط الرمزية.
- `channels.zalo.dmPolicy`: `pairing | allowlist | open | disabled` (الافتراضي: pairing).
- `channels.zalo.allowFrom`: قائمة سماح الرسائل الخاصة (معرّفات المستخدمين). يتطلب `open` وجود `"*"`. سيطلب المعالج المعرّفات الرقمية.
- `channels.zalo.groupPolicy`: `open | allowlist | disabled` (الافتراضي: allowlist). موجود في الإعدادات؛ راجع [الإمكانات](#capabilities) و[التحكم في الوصول (المجموعات)](#access-control-groups) لسلوك بوتات Marketplace الحالي.
- `channels.zalo.groupAllowFrom`: قائمة سماح مرسلي المجموعات (معرّفات المستخدمين). ترجع إلى `allowFrom` عندما لا تكون معيّنة.
- `channels.zalo.mediaMaxMb`: الحد الأقصى للوسائط الواردة/الصادرة (MB، الافتراضي 5).
- `channels.zalo.webhookUrl`: تمكين وضع webhook (يتطلب HTTPS).
- `channels.zalo.webhookSecret`: سر webhook (8-256 حرفًا).
- `channels.zalo.webhookPath`: مسار webhook على خادم HTTP الخاص بالبوابة.
- `channels.zalo.proxy`: عنوان URL للوكيل لطلبات API.
خيارات الحسابات المتعددة:
- `channels.zalo.accounts.<id>.botToken`: رمز مميز لكل حساب.
- `channels.zalo.accounts.<id>.tokenFile`: ملف رمز مميز عادي لكل حساب. يتم رفض الروابط الرمزية.
- `channels.zalo.accounts.<id>.name`: اسم العرض.
- `channels.zalo.accounts.<id>.enabled`: تمكين/تعطيل الحساب.
- `channels.zalo.accounts.<id>.dmPolicy`: سياسة الرسائل الخاصة لكل حساب.
- `channels.zalo.accounts.<id>.allowFrom`: قائمة السماح لكل حساب.
- `channels.zalo.accounts.<id>.groupPolicy`: سياسة المجموعات لكل حساب. موجودة في الإعدادات؛ راجع [الإمكانات](#capabilities) و[التحكم في الوصول (المجموعات)](#access-control-groups) لسلوك بوتات Marketplace الحالي.
- `channels.zalo.accounts.<id>.groupAllowFrom`: قائمة سماح مرسلي المجموعات لكل حساب.
- `channels.zalo.accounts.<id>.webhookUrl`: عنوان URL لـ webhook لكل حساب.
- `channels.zalo.accounts.<id>.webhookSecret`: سر webhook لكل حساب.
- `channels.zalo.accounts.<id>.webhookPath`: مسار webhook لكل حساب.
- `channels.zalo.accounts.<id>.proxy`: عنوان URL للوكيل لكل حساب.
## ذو صلة
- [نظرة عامة على القنوات](/channels) — جميع القنوات المدعومة
- [الاقتران](/channels/pairing) — مصادقة الرسائل الخاصة وتدفق الاقتران
- [المجموعات](/channels/groups) — سلوك الدردشة الجماعية والتقييد بالإشارة
- [توجيه القنوات](/channels/channel-routing) — توجيه الجلسات للرسائل
- [الأمان](/gateway/security) — نموذج الوصول والتقوية

202
docs/ar/channels/zalouser.md Normal file
View File

@ -0,0 +1,202 @@
---
read_when:
- إعداد Zalo Personal لـ OpenClaw
- تصحيح مشكلات تسجيل الدخول أو تدفق الرسائل في Zalo Personal
summary: دعم حساب Zalo الشخصي عبر `zca-js` الأصلي (تسجيل دخول QR)، والقدرات، والإعدادات
title: Zalo Personal
x-i18n:
generated_at: "2026-04-05T12:37:25Z"
model: gpt-5.4
provider: openai
source_hash: 331b95041463185472d242cb0a944972f0a8e99df8120bda6350eca86ad5963f
source_path: channels/zalouser.md
workflow: 15
---
# Zalo Personal (غير رسمي)
الحالة: تجريبي. يقوم هذا التكامل بأتمتة **حساب Zalo شخصي** عبر `zca-js` الأصلي داخل OpenClaw.
> **تحذير:** هذا تكامل غير رسمي وقد يؤدي إلى تعليق الحساب أو حظره. استخدمه على مسؤوليتك الخاصة.
## plugin المضمّن
يأتي Zalo Personal كـ plugin مضمّن في إصدارات OpenClaw الحالية، لذلك لا تحتاج
البنيات المعبأة العادية إلى تثبيت منفصل.
إذا كنت تستخدم إصدارًا أقدم أو تثبيتًا مخصصًا يستبعد Zalo Personal،
فثبّته يدويًا:
- ثبّت عبر CLI: `openclaw plugins install @openclaw/zalouser`
- أو من نسخة checkout للمصدر: `openclaw plugins install ./path/to/local/zalouser-plugin`
- التفاصيل: [Plugins](/tools/plugin)
لا يلزم وجود ملف CLI تنفيذي خارجي لـ `zca`/`openzca`.
## إعداد سريع (للمبتدئين)
1. تأكد من أن plugin الخاص بـ Zalo Personal متاح.
- تتضمنه إصدارات OpenClaw المعبأة الحالية بالفعل.
- يمكن لعمليات التثبيت الأقدم/المخصصة إضافته يدويًا باستخدام الأوامر أعلاه.
2. سجّل الدخول (QR، على جهاز Gateway):
- `openclaw channels login --channel zalouser`
- امسح رمز QR باستخدام تطبيق Zalo على الهاتف المحمول.
3. فعّل القناة:
```json5
{
channels: {
zalouser: {
enabled: true,
dmPolicy: "pairing",
},
},
}
```
4. أعد تشغيل Gateway (أو أكمل الإعداد).
5. يكون الوصول إلى الرسائل المباشرة مضبوطًا افتراضيًا على الاقتران؛ وافق على رمز الاقتران عند أول تواصل.
## ما هو
- يعمل بالكامل داخل العملية عبر `zca-js`.
- يستخدم مستمعي أحداث أصليين لاستقبال الرسائل الواردة.
- يرسل الردود مباشرة عبر JS API ‏(نص/وسائط/رابط).
- مصمم لحالات استخدام "الحساب الشخصي" حيث لا تكون Zalo Bot API متاحة.
## التسمية
معرّف القناة هو `zalouser` لتوضيح أن هذا التكامل يؤتمت **حساب مستخدم Zalo شخصي** (غير رسمي). ونحتفظ بالاسم `zalo` لتكامل رسمي محتمل مستقبلاً مع Zalo API.
## العثور على المعرّفات (الدليل)
استخدم CLI الخاص بالدليل لاكتشاف الجهات النظيرة/المجموعات ومعرّفاتها:
```bash
openclaw directory self --channel zalouser
openclaw directory peers list --channel zalouser --query "name"
openclaw directory groups list --channel zalouser --query "work"
```
## الحدود
- يُقسَّم النص الصادر إلى أجزاء بحوالي 2000 حرف (حدود عميل Zalo).
- يكون البث المتدفق محظورًا افتراضيًا.
## التحكم في الوصول (الرسائل المباشرة)
يدعم `channels.zalouser.dmPolicy` القيم التالية: `pairing | allowlist | open | disabled` (الافتراضي: `pairing`).
يقبل `channels.zalouser.allowFrom` معرّفات المستخدمين أو الأسماء. أثناء الإعداد، تُحوَّل الأسماء إلى معرّفات باستخدام البحث عن جهات الاتصال داخل العملية في plugin.
للموافقة:
- `openclaw pairing list zalouser`
- `openclaw pairing approve zalouser <code>`
## الوصول إلى المجموعات (اختياري)
- الافتراضي: `channels.zalouser.groupPolicy = "open"` ‏(المجموعات مسموح بها). استخدم `channels.defaults.groupPolicy` لتجاوز القيمة الافتراضية عند عدم ضبطها.
- للتقييد إلى قائمة سماح:
- `channels.zalouser.groupPolicy = "allowlist"`
- `channels.zalouser.groups` ‏(يجب أن تكون المفاتيح معرّفات مجموعات مستقرة؛ وتُحوَّل الأسماء إلى معرّفات عند بدء التشغيل عندما يكون ذلك ممكنًا)
- `channels.zalouser.groupAllowFrom` ‏(يتحكم في المرسلين داخل المجموعات المسموح بها الذين يمكنهم تشغيل البوت)
- لحظر جميع المجموعات: `channels.zalouser.groupPolicy = "disabled"`.
- يمكن لمعالج الإعداد المطالبة بقوائم سماح المجموعات.
- عند بدء التشغيل، يحوّل OpenClaw أسماء المجموعات/المستخدمين في قوائم السماح إلى معرّفات ويسجل هذا الربط.
- تكون مطابقة قائمة سماح المجموعات بحسب المعرّف فقط افتراضيًا. ويتم تجاهل الأسماء التي لم يتم حلها لأغراض التخويل ما لم يتم تمكين `channels.zalouser.dangerouslyAllowNameMatching: true`.
- يُعد `channels.zalouser.dangerouslyAllowNameMatching: true` وضع توافق احتياطي يعيد تمكين المطابقة باستخدام أسماء المجموعات القابلة للتغيير.
- إذا لم يتم ضبط `groupAllowFrom`، فإن وقت التشغيل يعود إلى `allowFrom` لفحوصات مرسلي المجموعات.
- تنطبق فحوصات المرسل على كل من رسائل المجموعات العادية وأوامر التحكم (على سبيل المثال `/new` و`/reset`).
مثال:
```json5
{
channels: {
zalouser: {
groupPolicy: "allowlist",
groupAllowFrom: ["1471383327500481391"],
groups: {
"123456789": { allow: true },
"Work Chat": { allow: true },
},
},
},
}
```
### بوابة الإشارات في المجموعات
- يتحكم `channels.zalouser.groups.<group>.requireMention` فيما إذا كانت الردود في المجموعات تتطلب إشارة.
- ترتيب الحل: معرّف/اسم المجموعة المطابق تمامًا -> slug المجموعة المطبع -> `*` -> الافتراضي (`true`).
- ينطبق هذا على كل من المجموعات المدرجة في قائمة السماح ووضع المجموعات المفتوح.
- يمكن لأوامر التحكم المصرّح بها (على سبيل المثال `/new`) تجاوز بوابة الإشارات.
- عندما يتم تخطي رسالة مجموعة لأن الإشارة مطلوبة، يخزنها OpenClaw كسجل مجموعة معلّق ويضمّنها في رسالة المجموعة التالية التي تتم معالجتها.
- يكون حد سجل المجموعات افتراضيًا هو `messages.groupChat.historyLimit` (مع تراجع إلى `50`). ويمكنك تجاوزه لكل حساب عبر `channels.zalouser.historyLimit`.
مثال:
```json5
{
channels: {
zalouser: {
groupPolicy: "allowlist",
groups: {
"*": { allow: true, requireMention: true },
"Work Chat": { allow: true, requireMention: false },
},
},
},
}
```
## حسابات متعددة
ترتبط الحسابات بملفات `zalouser` الشخصية في حالة OpenClaw. مثال:
```json5
{
channels: {
zalouser: {
enabled: true,
defaultAccount: "default",
accounts: {
work: { enabled: true, profile: "work" },
},
},
},
}
```
## الكتابة والتفاعلات وإقرارات التسليم
- يرسل OpenClaw حدث كتابة قبل إرسال الرد (بأفضل جهد ممكن).
- الإجراء `react` لتفاعلات الرسائل مدعوم لـ `zalouser` في إجراءات القنوات.
- استخدم `remove: true` لإزالة رمز emoji تفاعلي محدد من رسالة.
- دلالات التفاعلات: [Reactions](/tools/reactions)
- بالنسبة إلى الرسائل الواردة التي تتضمن بيانات تعريف الحدث، يرسل OpenClaw إقرارات بالتسليم والرؤية (بأفضل جهد ممكن).
## استكشاف الأخطاء وإصلاحها
**تسجيل الدخول لا يستمر:**
- `openclaw channels status --probe`
- أعد تسجيل الدخول: `openclaw channels logout --channel zalouser && openclaw channels login --channel zalouser`
**لم يتم حل اسم قائمة السماح/المجموعة:**
- استخدم المعرفات الرقمية في `allowFrom`/`groupAllowFrom`/`groups`، أو أسماء الأصدقاء/المجموعات المطابقة تمامًا.
**تمت الترقية من إعداد قديم قائم على CLI:**
- أزل أي افتراضات قديمة عن عملية `zca` خارجية.
- تعمل القناة الآن بالكامل داخل OpenClaw من دون ملفات CLI تنفيذية خارجية.
## ذو صلة
- [نظرة عامة على القنوات](/channels) — جميع القنوات المدعومة
- [الاقتران](/channels/pairing) — مصادقة الرسائل المباشرة وتدفق الاقتران
- [المجموعات](/channels/groups) — سلوك الدردشة الجماعية وبوابة الإشارات
- [توجيه القنوات](/channels/channel-routing) — توجيه الجلسات للرسائل
- [الأمان](/gateway/security) — نموذج الوصول والتقوية

73
docs/ar/ci.md Normal file
View File

@ -0,0 +1,73 @@
---
read_when:
- تحتاج إلى فهم سبب تشغيل وظيفة CI أو عدم تشغيلها
- أنت تصحح أخطاء فحوصات GitHub Actions الفاشلة
summary: رسم وظائف CI البياني، وبوابات النطاق، والمكافئات المحلية للأوامر
title: مسار CI
x-i18n:
generated_at: "2026-04-05T12:37:27Z"
model: gpt-5.4
provider: openai
source_hash: 5a95b6e584b4309bc249866ea436b4dfe30e0298ab8916eadbc344edae3d1194
source_path: ci.md
workflow: 15
---
# مسار CI
يعمل CI عند كل دفع إلى `main` وكل pull request. ويستخدم تحديد نطاق ذكيًا لتخطي الوظائف المكلفة عندما تكون التغييرات مقتصرة على مناطق غير مرتبطة.
## نظرة عامة على الوظائف
| الوظيفة | الغرض | وقت التشغيل |
| ----------------------- | ----------------------------------------------------------------------------------------- | ----------------------------------- |
| `preflight` | اكتشاف التغييرات الخاصة بالوثائق فقط، والنطاقات المتغيرة، والإضافات المتغيرة، وبناء CI manifest | دائمًا في عمليات الدفع وطلبات السحب غير المسودة |
| `security-fast` | اكتشاف المفاتيح الخاصة، وتدقيق workflow عبر `zizmor`، وتدقيق تبعيات الإنتاج | دائمًا في عمليات الدفع وطلبات السحب غير المسودة |
| `build-artifacts` | بناء `dist/` وControl UI مرة واحدة، ورفع artifacts قابلة لإعادة الاستخدام للوظائف اللاحقة | التغييرات المرتبطة بـ Node |
| `checks-fast-core` | مسارات صحة Linux السريعة مثل فحوصات الحزمة/عقد الإضافات/البروتوكول | التغييرات المرتبطة بـ Node |
| `checks-fast-extensions` | تجميع مسارات تقسيم الإضافات بعد اكتمال `checks-fast-extensions-shard` | التغييرات المرتبطة بـ Node |
| `extension-fast` | اختبارات مركزة للإضافات المضمّنة التي تغيّرت فقط | عند اكتشاف تغييرات في الإضافات |
| `check` | البوابة المحلية الرئيسية في CI: ‏`pnpm check` بالإضافة إلى `pnpm build:strict-smoke` | التغييرات المرتبطة بـ Node |
| `check-additional` | حمايات البنية والحدود بالإضافة إلى حزمة اختبار تراجع مراقبة gateway | التغييرات المرتبطة بـ Node |
| `build-smoke` | اختبارات smoke للـ CLI المبني واختبار smoke لذاكرة بدء التشغيل | التغييرات المرتبطة بـ Node |
| `checks` | مسارات Linux Node الأثقل: الاختبارات الكاملة، واختبارات القنوات، وتوافق Node 22 للدفع فقط | التغييرات المرتبطة بـ Node |
| `check-docs` | تنسيق الوثائق وفحصها واختبارات الروابط المعطلة | عند تغيير الوثائق |
| `skills-python` | ‏Ruff + pytest للـ Skills المعتمدة على Python | التغييرات المرتبطة بـ Python Skills |
| `checks-windows` | مسارات اختبارات خاصة بـ Windows | التغييرات المرتبطة بـ Windows |
| `macos-node` | مسار اختبارات TypeScript على macOS باستخدام artifacts المبنية المشتركة | التغييرات المرتبطة بـ macOS |
| `macos-swift` | فحص Swift وبناؤه واختباراته لتطبيق macOS | التغييرات المرتبطة بـ macOS |
| `android` | مصفوفة بناء Android واختباره | التغييرات المرتبطة بـ Android |
## ترتيب الإخفاق السريع
تُرتب الوظائف بحيث تفشل الفحوصات الرخيصة قبل تشغيل الوظائف المكلفة:
1. يقرر `preflight` أي المسارات موجودة أصلًا. ومنطق `docs-scope` و`changed-scope` هما خطوتان داخل هذه الوظيفة، وليسا وظيفتين مستقلتين.
2. تفشل `security-fast` و`check` و`check-additional` و`check-docs` و`skills-python` بسرعة من دون انتظار وظائف artifact ومصفوفات المنصات الأثقل.
3. يتداخل `build-artifacts` مع مسارات Linux السريعة حتى يتمكن المستهلكون اللاحقون من البدء بمجرد جاهزية البنية المشتركة.
4. بعد ذلك تتفرع مسارات المنصات ووقت التشغيل الأثقل: `checks-fast-core` و`checks-fast-extensions` و`extension-fast` و`checks` و`checks-windows` و`macos-node` و`macos-swift` و`android`.
يعيش منطق النطاق في `scripts/ci-changed-scope.mjs` وتغطيه اختبارات الوحدة في `src/scripts/ci-changed-scope.test.ts`.
ويعيد workflow المنفصل `install-smoke` استخدام نص النطاق نفسه عبر وظيفة `preflight` الخاصة به. فهو يحسب `run_install_smoke` من إشارة changed-smoke الأضيق، لذلك لا يعمل smoke الخاص بـ Docker/install إلا للتغييرات المرتبطة بالتثبيت والتعبئة والحاويات.
في عمليات الدفع، تضيف مصفوفة `checks` مسار `compat-node22` الخاص بالدفع فقط. أما في pull requests، فيُتخطى هذا المسار وتظل المصفوفة مركزة على مسارات الاختبار/القنوات العادية.
## المشغّلات
| المشغّل | الوظائف |
| -------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `blacksmith-16vcpu-ubuntu-2404` | `preflight` و`security-fast` و`build-artifacts` وفحوصات Linux وفحوصات الوثائق وPython Skills و`android` |
| `blacksmith-32vcpu-windows-2025` | `checks-windows` |
| `macos-latest` | `macos-node` و`macos-swift` |
## المكافئات المحلية
```bash
pnpm check # الأنواع + lint + format
pnpm build:strict-smoke
pnpm test:gateway:watch-regression
pnpm test # اختبارات vitest
pnpm test:channels
pnpm check:docs # تنسيق الوثائق + lint + الروابط المعطلة
pnpm build # بناء dist عندما تكون مسارات CI artifact/build-smoke مهمة
```

322
docs/ar/cli/acp.md Normal file
View File

@ -0,0 +1,322 @@
---
read_when:
- عند إعداد تكاملات IDE المستندة إلى ACP
- عند تصحيح توجيه جلسات ACP إلى البوابة
summary: تشغيل جسر ACP لتكاملات IDE
title: acp
x-i18n:
generated_at: "2026-04-05T12:38:02Z"
model: gpt-5.4
provider: openai
source_hash: 2461b181e4a97dd84580581e9436ca1947a224decce8044132dbcf7fb2b7502c
source_path: cli/acp.md
workflow: 15
---
# acp
شغّل جسر [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) الذي يتحدث إلى بوابة OpenClaw.
يتحدث هذا الأمر بروتوكول ACP عبر stdio لبيئات IDE ويعيد توجيه المطالبات إلى البوابة
عبر WebSocket. ويحافظ على ربط جلسات ACP بمفاتيح جلسات البوابة.
إن `openclaw acp` هو جسر ACP مدعوم بالبوابة، وليس بيئة تشغيل تحرير
أصلية كاملة لـ ACP. وهو يركز على توجيه الجلسات، وتسليم المطالبات، وتحديثات
البث الأساسية.
إذا كنت تريد أن يتحدث عميل MCP خارجي مباشرةً إلى محادثات قنوات OpenClaw
بدلًا من استضافة جلسة harness لـ ACP، فاستخدم
[`openclaw mcp serve`](/cli/mcp) بدلًا من ذلك.
## ما الذي لا يمثله هذا
غالبًا ما يختلط هذا الصفحة بجلسات harness الخاصة بـ ACP.
يعني `openclaw acp` ما يلي:
- يعمل OpenClaw كخادم ACP
- يتصل IDE أو عميل ACP بـ OpenClaw
- يعيد OpenClaw توجيه هذا العمل إلى جلسة في البوابة
وهذا يختلف عن [ACP Agents](/tools/acp-agents)، حيث يشغّل OpenClaw
حزامًا خارجيًا مثل Codex أو Claude Code من خلال `acpx`.
قاعدة سريعة:
- إذا كان المحرر/العميل يريد التحدث عبر ACP إلى OpenClaw: استخدم `openclaw acp`
- إذا كان ينبغي على OpenClaw تشغيل Codex/Claude/Gemini كـ ACP harness: استخدم `/acp spawn` و[ACP Agents](/tools/acp-agents)
## مصفوفة التوافق
| مجال ACP | الحالة | ملاحظات |
| --------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `initialize`, `newSession`, `prompt`, `cancel` | مُنفّذ | تدفق الجسر الأساسي عبر stdio إلى Gateway chat/send + الإلغاء. |
| `listSessions`, أوامر slash | مُنفّذ | يعمل سرد الجلسات مقابل حالة جلسات البوابة؛ ويتم الإعلان عن الأوامر عبر `available_commands_update`. |
| `loadSession` | جزئي | يعيد ربط جلسة ACP بمفتاح جلسة في البوابة ويعيد تشغيل سجل النصوص المخزن للمستخدم/المساعد. ولا يُعاد بناء سجل الأدوات/النظام بعد. |
| محتوى المطالبة (`text`, و`resource` المضمّن، والصور) | جزئي | يتم تسطيح النص/الموارد إلى دخل الدردشة؛ وتتحول الصور إلى مرفقات في البوابة. |
| أوضاع الجلسات | جزئي | `session/set_mode` مدعوم، ويعرض الجسر عناصر تحكم أولية مدعومة بالبوابة لمستوى التفكير، وإسهاب الأدوات، والاستدلال، وتفاصيل الاستخدام، والإجراءات المرتفعة. وما تزال أسطح الأوضاع/الإعدادات الأوسع الأصلية لـ ACP خارج النطاق. |
| معلومات الجلسة وتحديثات الاستخدام | جزئي | يصدر الجسر إشعارات `session_info_update` و`usage_update` بأفضل جهد من لقطات جلسات البوابة المخزنة مؤقتًا. والاستخدام تقريبي ولا يُرسل إلا عندما تكون مجاميع الرموز في البوابة معلّمة على أنها حديثة. |
| بث الأدوات | جزئي | تتضمن أحداث `tool_call` / `tool_call_update` الإدخال/الإخراج الخام، ومحتوى النص، ومواقع الملفات بأفضل جهد عندما تكشفها وسائط/نتائج أدوات البوابة. ولا تزال الطرفيات المضمّنة ومخرجات الفروقات الأصلية الأغنى غير مكشوفة. |
| خوادم MCP لكل جلسة (`mcpServers`) | غير مدعوم | يرفض وضع الجسر طلبات خوادم MCP لكل جلسة. قم بإعداد MCP على بوابة OpenClaw أو الوكيل بدلًا من ذلك. |
| أساليب نظام ملفات العميل (`fs/read_text_file`, `fs/write_text_file`) | غير مدعوم | لا يستدعي الجسر أساليب نظام ملفات عميل ACP. |
| أساليب طرفية العميل (`terminal/*`) | غير مدعوم | لا ينشئ الجسر طرفيات لعميل ACP ولا يبث معرّفات الطرفيات عبر استدعاءات الأدوات. |
| خطط الجلسات / بث الأفكار | غير مدعوم | يصدر الجسر حاليًا نص المخرجات وحالة الأدوات، وليس تحديثات الخطط أو الأفكار الخاصة بـ ACP. |
## القيود المعروفة
- يعيد `loadSession` تشغيل سجل النصوص المخزن للمستخدم والمساعد، لكنه لا
يعيد بناء استدعاءات الأدوات التاريخية أو إشعارات النظام أو أنواع الأحداث
الأصلية الأكثر غنى في ACP.
- إذا شارك عدة عملاء ACP مفتاح جلسة البوابة نفسه، فإن توجيه الأحداث والإلغاء
يكون بأفضل جهد بدلًا من العزل الصارم لكل عميل. ويفضَّل استخدام جلسات
`acp:<uuid>` المعزولة افتراضيًا عندما تحتاج إلى أدوار محلية نظيفة في المحرر.
- تُترجم حالات التوقف في البوابة إلى أسباب توقف في ACP، لكن هذا الربط
أقل تعبيرًا من بيئة تشغيل أصلية كاملة لـ ACP.
- تعرِض عناصر التحكم الأولية في الجلسات حاليًا مجموعة مركزة من مفاتيح البوابة:
مستوى التفكير، وإسهاب الأدوات، والاستدلال، وتفاصيل الاستخدام، والإجراءات
المرتفعة. ولم يتم بعد كشف اختيار النموذج وعناصر تحكم مضيف exec كخيارات
إعداد في ACP.
- تُشتق `session_info_update` و`usage_update` من لقطات جلسات البوابة،
لا من محاسبة وقت تشغيل أصلية مباشرة لـ ACP. والاستخدام تقريبي،
ولا يتضمن بيانات تكلفة، ولا يُصدر إلا عندما تضع البوابة علامة
"حديث" على بيانات إجمالي الرموز.
- بيانات متابعة الأدوات تعمل بأفضل جهد. يستطيع الجسر إظهار مسارات الملفات التي
تظهر في وسائط/نتائج أدوات معروفة، لكنه لا يصدر بعد طرفيات ACP أو
فروقات ملفات منظمة.
## الاستخدام
```bash
openclaw acp
# بوابة بعيدة
openclaw acp --url wss://gateway-host:18789 --token <token>
# بوابة بعيدة (الرمز من ملف)
openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token
# الإرفاق بمفتاح جلسة موجود
openclaw acp --session agent:main:main
# الإرفاق حسب التسمية (يجب أن تكون موجودة بالفعل)
openclaw acp --session-label "support inbox"
# إعادة تعيين مفتاح الجلسة قبل أول مطالبة
openclaw acp --session agent:main:main --reset-session
```
## عميل ACP (تصحيح)
استخدم عميل ACP المضمّن للتحقق السريع من الجسر من دون IDE.
فهو يشغّل جسر ACP ويسمح لك بكتابة المطالبات بشكل تفاعلي.
```bash
openclaw acp client
# وجّه الجسر الذي تم تشغيله إلى بوابة بعيدة
openclaw acp client --server-args --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token
# تجاوز أمر الخادم (الافتراضي: openclaw)
openclaw acp client --server "node" --server-args openclaw.mjs acp --url ws://127.0.0.1:19001
```
نموذج الأذونات (وضع تصحيح العميل):
- تعتمد الموافقة التلقائية على قائمة سماح ولا تنطبق إلا على معرّفات الأدوات الأساسية الموثوقة.
- تقتصر الموافقة التلقائية لـ `read` على دليل العمل الحالي (`--cwd` عند ضبطه).
- يوافق ACP تلقائيًا فقط على فئات ضيقة للقراءة فقط: استدعاءات `read` ضمن cwd النشط، إضافة إلى أدوات البحث للقراءة فقط (`search`, `web_search`, `memory_search`). وتتطلب الأدوات غير المعروفة/غير الأساسية، وعمليات القراءة خارج النطاق، والأدوات القادرة على exec، وأدوات مستوى التحكم، والأدوات المعدِّلة، والتدفقات التفاعلية دائمًا موافقة صريحة عبر المطالبة.
- تُعامل `toolCall.kind` المقدمة من الخادم على أنها بيانات وصفية غير موثوقة (وليست مصدر تفويض).
- تختلف سياسة جسر ACP هذا عن أذونات ACPX harness. إذا شغّلت OpenClaw عبر الخلفية `acpx`، فإن `plugins.entries.acpx.config.permissionMode=approve-all` هو مفتاح الطوارئ "yolo" لتلك الجلسة من الـ harness.
## كيفية استخدام هذا
استخدم ACP عندما يتحدث IDE (أو عميل آخر) Agent Client Protocol وتريد
أن يدير جلسة بوابة OpenClaw.
1. تأكد من أن البوابة قيد التشغيل (محليًا أو عن بُعد).
2. اضبط هدف البوابة (بالإعداد أو العلامات).
3. وجّه IDE لديك لتشغيل `openclaw acp` عبر stdio.
مثال على الإعداد (محفوظ):
```bash
openclaw config set gateway.remote.url wss://gateway-host:18789
openclaw config set gateway.remote.token <token>
```
مثال على تشغيل مباشر (من دون كتابة إعداد):
```bash
openclaw acp --url wss://gateway-host:18789 --token <token>
# مفضّل من أجل أمان العملية المحلية
openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token
```
## اختيار الوكلاء
لا يختار ACP الوكلاء مباشرةً. بل يوجّه حسب مفتاح جلسة البوابة.
استخدم مفاتيح جلسات على مستوى الوكيل لاستهداف وكيل محدد:
```bash
openclaw acp --session agent:main:main
openclaw acp --session agent:design:main
openclaw acp --session agent:qa:bug-123
```
تُربط كل جلسة ACP بمفتاح جلسة واحد في البوابة. ويمكن لوكيل واحد أن يملك
جلسات عديدة؛ ويستخدم ACP افتراضيًا جلسة معزولة `acp:<uuid>` ما لم تتجاوز
المفتاح أو التسمية.
لا يتم دعم `mcpServers` لكل جلسة في وضع الجسر. وإذا أرسل عميل ACP
هذه القيم أثناء `newSession` أو `loadSession`، فسيعيد الجسر خطأً
واضحًا بدلًا من تجاهلها بصمت.
إذا كنت تريد أن ترى الجلسات المدعومة بـ ACPX أدوات plugin الخاصة بـ OpenClaw، ففعّل
جسر plugin الخاص بـ ACPX على جانب البوابة بدلًا من محاولة تمرير
`mcpServers` لكل جلسة. راجع [ACP Agents](/tools/acp-agents#plugin-tools-mcp-bridge).
## الاستخدام من `acpx` (Codex وClaude وغيرهما من عملاء ACP)
إذا كنت تريد أن يتحدث وكيل برمجي مثل Codex أو Claude Code إلى
بوت OpenClaw لديك عبر ACP، فاستخدم `acpx` مع الهدف المضمّن `openclaw`.
التدفق النموذجي:
1. شغّل البوابة وتأكد من أن جسر ACP يستطيع الوصول إليها.
2. وجّه `acpx openclaw` إلى `openclaw acp`.
3. استهدف مفتاح جلسة OpenClaw الذي تريد أن يستخدمه وكيل البرمجة.
أمثلة:
```bash
# طلب لمرة واحدة إلى جلسة OpenClaw ACP الافتراضية
acpx openclaw exec "Summarize the active OpenClaw session state."
# جلسة دائمة مسماة للأدوار اللاحقة
acpx openclaw sessions ensure --name codex-bridge
acpx openclaw -s codex-bridge --cwd /path/to/repo \
"Ask my OpenClaw work agent for recent context relevant to this repo."
```
إذا كنت تريد أن يستهدف `acpx openclaw` بوابة ومفتاح جلسة محددين في كل
مرة، فتجاوز أمر الوكيل `openclaw` في `~/.acpx/config.json`:
```json
{
"agents": {
"openclaw": {
"command": "env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 openclaw acp --url ws://127.0.0.1:18789 --token-file ~/.openclaw/gateway.token --session agent:main:main"
}
}
}
```
بالنسبة إلى نسخة OpenClaw محلية ضمن المستودع، استخدم نقطة دخول CLI المباشرة بدلًا من
مشغّل التطوير حتى يظل تدفق ACP نظيفًا. على سبيل المثال:
```bash
env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 node openclaw.mjs acp ...
```
وهذه هي أسهل طريقة لجعل Codex أو Claude Code أو أي عميل آخر مدرك لـ ACP
يسحب معلومات سياقية من وكيل OpenClaw من دون كشط طرفية.
## إعداد محرر Zed
أضف وكيل ACP مخصصًا في `~/.config/zed/settings.json` (أو استخدم واجهة إعدادات Zed):
```json
{
"agent_servers": {
"OpenClaw ACP": {
"type": "custom",
"command": "openclaw",
"args": ["acp"],
"env": {}
}
}
}
```
لاستهداف بوابة أو وكيل محدد:
```json
{
"agent_servers": {
"OpenClaw ACP": {
"type": "custom",
"command": "openclaw",
"args": [
"acp",
"--url",
"wss://gateway-host:18789",
"--token",
"<token>",
"--session",
"agent:design:main"
],
"env": {}
}
}
}
```
في Zed، افتح لوحة Agent واختر “OpenClaw ACP” لبدء سلسلة محادثة.
## ربط الجلسات
افتراضيًا، تحصل جلسات ACP على مفتاح جلسة معزول في البوابة مع البادئة `acp:`.
ولإعادة استخدام جلسة معروفة، مرّر مفتاح جلسة أو تسمية:
- `--session <key>`: استخدم مفتاح جلسة محددًا في البوابة.
- `--session-label <label>`: حل جلسة موجودة حسب التسمية.
- `--reset-session`: أنشئ معرّف جلسة جديدًا لذلك المفتاح (المفتاح نفسه، وسجل جديد).
إذا كان عميل ACP لديك يدعم البيانات الوصفية، فيمكنك التجاوز لكل جلسة:
```json
{
"_meta": {
"sessionKey": "agent:main:main",
"sessionLabel": "support inbox",
"resetSession": true
}
}
```
تعرّف أكثر على مفاتيح الجلسات في [/concepts/session](/concepts/session).
## الخيارات
- `--url <url>`: عنوان WebSocket URL للبوابة (يستخدم `gateway.remote.url` افتراضيًا عند إعداده).
- `--token <token>`: رمز مصادقة البوابة.
- `--token-file <path>`: قراءة رمز مصادقة البوابة من ملف.
- `--password <password>`: كلمة مرور مصادقة البوابة.
- `--password-file <path>`: قراءة كلمة مرور مصادقة البوابة من ملف.
- `--session <key>`: مفتاح الجلسة الافتراضي.
- `--session-label <label>`: تسمية الجلسة الافتراضية المراد حلها.
- `--require-existing`: يفشل إذا لم يكن مفتاح/تسمية الجلسة موجودًا.
- `--reset-session`: إعادة تعيين مفتاح الجلسة قبل أول استخدام.
- `--no-prefix-cwd`: عدم إضافة دليل العمل كبادئة للمطالبات.
- `--provenance <off|meta|meta+receipt>`: تضمين بيانات وصفية أو إيصالات provenance الخاصة بـ ACP.
- `--verbose, -v`: تسجيلات مفصلة إلى stderr.
ملاحظة أمنية:
- قد تكون `--token` و`--password` مرئيتين في قوائم العمليات المحلية على بعض الأنظمة.
- يفضَّل استخدام `--token-file`/`--password-file` أو متغيرات البيئة (`OPENCLAW_GATEWAY_TOKEN`, `OPENCLAW_GATEWAY_PASSWORD`).
- يتبع تحليل مصادقة البوابة العقد المشترك المستخدم من قِبل عملاء البوابة الآخرين:
- الوضع المحلي: البيئة (`OPENCLAW_GATEWAY_*`) -> `gateway.auth.*` -> الرجوع إلى `gateway.remote.*` فقط عندما لا تكون `gateway.auth.*` مضبوطة (تفشل SecretRefs المحلية المضبوطة لكن غير المحلولة بشكل مغلق)
- الوضع البعيد: `gateway.remote.*` مع الرجوع إلى البيئة/الإعداد وفق قواعد أسبقية الوضع البعيد
- `--url` آمن للتجاوز ولا يعيد استخدام بيانات اعتماد ضمنية من الإعداد/البيئة؛ مرّر `--token`/`--password` صريحين (أو نُسَخ الملف)
- تتلقى العمليات الفرعية في الخلفية وقت تشغيل ACP المتغير `OPENCLAW_SHELL=acp`، ويمكن استخدامه لقواعد سياق shell/profile خاصة.
- يضبط `openclaw acp client` القيمة `OPENCLAW_SHELL=acp-client` على عملية الجسر التي يتم تشغيلها.
### خيارات `acp client`
- `--cwd <dir>`: دليل العمل لجلسة ACP.
- `--server <command>`: أمر خادم ACP (الافتراضي: `openclaw`).
- `--server-args <args...>`: وسائط إضافية تمرَّر إلى خادم ACP.
- `--server-verbose`: تمكين التسجيلات المفصلة على خادم ACP.
- `--verbose, -v`: تسجيلات مفصلة للعميل.

64
docs/ar/cli/agent.md Normal file
View File

@ -0,0 +1,64 @@
---
read_when:
- تريد تشغيل دورة وكيل واحدة من النصوص البرمجية (مع تسليم الرد اختياريًا)
summary: مرجع CLI للأمر `openclaw agent` (تشغيل دورة وكيل واحدة عبر Gateway)
title: agent
x-i18n:
generated_at: "2026-04-05T12:37:32Z"
model: gpt-5.4
provider: openai
source_hash: 0627f943bc7f3556318008f76dc6150788cf06927dccdc7d2681acb98f257d56
source_path: cli/agent.md
workflow: 15
---
# `openclaw agent`
شغّل دورة وكيل عبر Gateway (استخدم `--local` للتشغيل المضمن).
استخدم `--agent <id>` لاستهداف وكيل مكوَّن مباشرةً.
مرّر محدد جلسة واحدًا على الأقل:
- `--to <dest>`
- `--session-id <id>`
- `--agent <id>`
ذو صلة:
- أداة إرسال الوكيل: [Agent send](/tools/agent-send)
## الخيارات
- `-m, --message <text>`: نص الرسالة المطلوب
- `-t, --to <dest>`: المستلم المستخدم لاشتقاق مفتاح الجلسة
- `--session-id <id>`: معرّف جلسة صريح
- `--agent <id>`: معرّف الوكيل؛ يتجاوز روابط التوجيه
- `--thinking <off|minimal|low|medium|high|xhigh>`: مستوى تفكير الوكيل
- `--verbose <on|off>`: حفظ مستوى التفصيل للجلسة
- `--channel <channel>`: قناة التسليم؛ احذفه لاستخدام قناة الجلسة الرئيسية
- `--reply-to <target>`: تجاوز هدف التسليم
- `--reply-channel <channel>`: تجاوز قناة التسليم
- `--reply-account <id>`: تجاوز حساب التسليم
- `--local`: شغّل الوكيل المضمن مباشرةً (بعد التحميل المسبق لسجل plugins)
- `--deliver`: أرسل الرد مرة أخرى إلى القناة/الهدف المحدد
- `--timeout <seconds>`: تجاوز مهلة الوكيل (الافتراضي 600 أو قيمة التكوين)
- `--json`: إخراج JSON
## أمثلة
```bash
openclaw agent --to +15555550123 --message "status update" --deliver
openclaw agent --agent ops --message "Summarize logs"
openclaw agent --session-id 1234 --message "Summarize inbox" --thinking medium
openclaw agent --to +15555550123 --message "Trace logs" --verbose on --json
openclaw agent --agent ops --message "Generate report" --deliver --reply-channel slack --reply-to "#reports"
openclaw agent --agent ops --message "Run locally" --local
```
## ملاحظات
- يعود وضع Gateway إلى الوكيل المضمن عندما يفشل طلب Gateway. استخدم `--local` لفرض التنفيذ المضمن من البداية.
- ما يزال `--local` يحمّل سجل plugins مسبقًا أولًا، لذلك تبقى providers والأدوات والقنوات التي توفرها plugins متاحة أثناء التشغيل المضمن.
- تؤثر `--channel` و`--reply-channel` و`--reply-account` في تسليم الرد، وليس في توجيه الجلسة.
- عندما يؤدي هذا الأمر إلى إعادة إنشاء `models.json`، يتم حفظ بيانات اعتماد المزوّد التي تديرها SecretRef كعلامات غير سرية (مثل أسماء متغيرات البيئة أو `secretref-env:ENV_VAR_NAME` أو `secretref-managed`) وليس كنصوص أسرار صريحة محلولة.
- تكون عمليات كتابة العلامات معتمدة على المصدر: يحفظ OpenClaw العلامات من لقطة التكوين المصدر النشطة، وليس من قيم الأسرار المحلولة وقت التشغيل.

227
docs/ar/cli/agents.md Normal file
View File

@ -0,0 +1,227 @@
---
read_when:
- أنت تريد عدة وكلاء معزولين (مساحات عمل + توجيه + مصادقة)
summary: مرجع CLI للأمر `openclaw agents` ‏(list/add/delete/bindings/bind/unbind/set identity)
title: agents
x-i18n:
generated_at: "2026-04-05T12:37:46Z"
model: gpt-5.4
provider: openai
source_hash: 90b90c4915993bd8af322c0590d4cb59baabb8940598ce741315f8f95ef43179
source_path: cli/agents.md
workflow: 15
---
# `openclaw agents`
إدارة الوكلاء المعزولين (مساحات العمل + المصادقة + التوجيه).
ذو صلة:
- التوجيه متعدد الوكلاء: [التوجيه متعدد الوكلاء](/concepts/multi-agent)
- مساحة عمل الوكيل: [مساحة عمل الوكيل](/concepts/agent-workspace)
- إعدادات ظهور Skills: [إعدادات Skills](/tools/skills-config)
## أمثلة
```bash
openclaw agents list
openclaw agents list --bindings
openclaw agents add work --workspace ~/.openclaw/workspace-work
openclaw agents add ops --workspace ~/.openclaw/workspace-ops --bind telegram:ops --non-interactive
openclaw agents bindings
openclaw agents bind --agent work --bind telegram:ops
openclaw agents unbind --agent work --bind telegram:ops
openclaw agents set-identity --workspace ~/.openclaw/workspace --from-identity
openclaw agents set-identity --agent main --avatar avatars/openclaw.png
openclaw agents delete work
```
## ارتباطات التوجيه
استخدم ارتباطات التوجيه لتثبيت حركة القناة الواردة على وكيل محدد.
إذا كنت تريد أيضًا Skills مرئية مختلفة لكل وكيل، فقم بإعداد
`agents.defaults.skills` و`agents.list[].skills` في `openclaw.json`. راجع
[إعدادات Skills](/tools/skills-config) و
[مرجع الإعدادات](/gateway/configuration-reference#agentsdefaultsskills).
عرض الارتباطات:
```bash
openclaw agents bindings
openclaw agents bindings --agent work
openclaw agents bindings --json
```
إضافة ارتباطات:
```bash
openclaw agents bind --agent work --bind telegram:ops --bind discord:guild-a
```
إذا حذفت `accountId` ‏(`--bind <channel>`)، فإن OpenClaw يحلّه من القيم الافتراضية للقناة وخطافات إعداد plugin عند توفرها.
إذا حذفت `--agent` في `bind` أو `unbind`، فإن OpenClaw يستهدف الوكيل الافتراضي الحالي.
### سلوك نطاق الارتباط
- الارتباط من دون `accountId` يطابق الحساب الافتراضي للقناة فقط.
- `accountId: "*"` هو التراجع على مستوى القناة (كل الحسابات)، وهو أقل تحديدًا من ارتباط حساب صريح.
- إذا كان الوكيل نفسه يملك بالفعل ارتباط قناة مطابقًا من دون `accountId`، ثم قمت لاحقًا بالارتباط باستخدام `accountId` صريح أو محلول، فإن OpenClaw يرقّي ذلك الارتباط الموجود في مكانه بدلًا من إضافة ارتباط مكرر.
مثال:
```bash
# initial channel-only binding
openclaw agents bind --agent work --bind telegram
# later upgrade to account-scoped binding
openclaw agents bind --agent work --bind telegram:ops
```
بعد الترقية، يصبح التوجيه لذلك الارتباط ضمن النطاق `telegram:ops`. إذا كنت تريد أيضًا توجيه الحساب الافتراضي، فأضفه صراحةً (على سبيل المثال `--bind telegram:default`).
إزالة الارتباطات:
```bash
openclaw agents unbind --agent work --bind telegram:ops
openclaw agents unbind --agent work --all
```
يقبل `unbind` إما `--all` أو قيمة واحدة أو أكثر من `--bind`، وليس كليهما معًا.
## سطح الأوامر
### `agents`
تشغيل `openclaw agents` من دون أمر فرعي يعادل `openclaw agents list`.
### `agents list`
الخيارات:
- `--json`
- `--bindings`: تضمين قواعد التوجيه الكاملة، وليس فقط الأعداد/الملخصات لكل وكيل
### `agents add [name]`
الخيارات:
- `--workspace <dir>`
- `--model <id>`
- `--agent-dir <dir>`
- `--bind <channel[:accountId]>` (قابل للتكرار)
- `--non-interactive`
- `--json`
ملاحظات:
- تمرير أي أعلام إضافة صريحة يحوّل الأمر إلى المسار غير التفاعلي.
- يتطلب الوضع غير التفاعلي اسم وكيل و`--workspace` معًا.
- `main` محجوز ولا يمكن استخدامه كمعرّف للوكيل الجديد.
### `agents bindings`
الخيارات:
- `--agent <id>`
- `--json`
### `agents bind`
الخيارات:
- `--agent <id>` (الافتراضي هو الوكيل الافتراضي الحالي)
- `--bind <channel[:accountId]>` (قابل للتكرار)
- `--json`
### `agents unbind`
الخيارات:
- `--agent <id>` (الافتراضي هو الوكيل الافتراضي الحالي)
- `--bind <channel[:accountId]>` (قابل للتكرار)
- `--all`
- `--json`
### `agents delete <id>`
الخيارات:
- `--force`
- `--json`
ملاحظات:
- لا يمكن حذف `main`.
- من دون `--force`، يلزم تأكيد تفاعلي.
- يتم نقل مجلدات مساحة العمل وحالة الوكيل وسجل الجلسة إلى سلة المهملات، ولا تُحذف نهائيًا.
## ملفات الهوية
يمكن أن تتضمن مساحة عمل كل وكيل ملف `IDENTITY.md` في جذر مساحة العمل:
- مسار مثال: `~/.openclaw/workspace/IDENTITY.md`
- يقرأ `set-identity --from-identity` من جذر مساحة العمل (أو من `--identity-file` صريح)
يتم حل مسارات الصورة الرمزية نسبةً إلى جذر مساحة العمل.
## تعيين الهوية
يكتب `set-identity` الحقول داخل `agents.list[].identity`:
- `name`
- `theme`
- `emoji`
- `avatar` (مسار نسبةً إلى مساحة العمل، أو URL من نوع http(s)، أو data URI)
الخيارات:
- `--agent <id>`
- `--workspace <dir>`
- `--identity-file <path>`
- `--from-identity`
- `--name <name>`
- `--theme <theme>`
- `--emoji <emoji>`
- `--avatar <value>`
- `--json`
ملاحظات:
- يمكن استخدام `--agent` أو `--workspace` لتحديد الوكيل المستهدف.
- إذا كنت تعتمد على `--workspace` وكان عدة وكلاء يشاركون مساحة العمل نفسها، يفشل الأمر ويطلب منك تمرير `--agent`.
- عند عدم توفير أي حقول هوية صريحة، يقرأ الأمر بيانات الهوية من `IDENTITY.md`.
التحميل من `IDENTITY.md`:
```bash
openclaw agents set-identity --workspace ~/.openclaw/workspace --from-identity
```
تجاوز الحقول صراحةً:
```bash
openclaw agents set-identity --agent main --name "OpenClaw" --emoji "🦞" --avatar avatars/openclaw.png
```
نموذج إعدادات:
```json5
{
agents: {
list: [
{
id: "main",
identity: {
name: "OpenClaw",
theme: "space lobster",
emoji: "🦞",
avatar: "avatars/openclaw.png",
},
},
],
},
}
```

143
docs/ar/cli/approvals.md Normal file
View File

@ -0,0 +1,143 @@
---
read_when:
- تريد تعديل موافقات exec من CLI
- تحتاج إلى إدارة قوائم السماح على مضيف gateway أو مضيفات العقد
summary: مرجع CLI للأمر `openclaw approvals` (موافقات exec لمضيف gateway أو مضيفات العقد)
title: approvals
x-i18n:
generated_at: "2026-04-05T12:37:40Z"
model: gpt-5.4
provider: openai
source_hash: 7b2532bfd3e6e6ce43c96a2807df2dd00cb7b4320b77a7dfd09bee0531da610e
source_path: cli/approvals.md
workflow: 15
---
# `openclaw approvals`
أدِر موافقات exec لـ **المضيف المحلي** أو **مضيف gateway** أو **مضيف عقدة**.
بشكل افتراضي، تستهدف الأوامر ملف الموافقات المحلي على القرص. استخدم `--gateway` لاستهداف gateway، أو `--node` لاستهداف عقدة معيّنة.
الاسم البديل: `openclaw exec-approvals`
ذو صلة:
- موافقات Exec: [Exec approvals](/tools/exec-approvals)
- العقد: [Nodes](/nodes)
## الأوامر الشائعة
```bash
openclaw approvals get
openclaw approvals get --node <id|name|ip>
openclaw approvals get --gateway
```
يعرض `openclaw approvals get` الآن سياسة exec الفعالة للأهداف المحلية وأهداف gateway وأهداف العقد:
- سياسة `tools.exec` المطلوبة
- سياسة ملف الموافقات الخاصة بالمضيف
- النتيجة الفعالة بعد تطبيق قواعد الأسبقية
الأسبقية مقصودة:
- ملف موافقات المضيف هو مصدر الحقيقة القابل للفرض
- يمكن لسياسة `tools.exec` المطلوبة أن تضيّق المقصود أو توسّعه، لكن النتيجة الفعالة ما تزال مشتقة من قواعد المضيف
- يجمع `--node` بين ملف موافقات مضيف العقدة وسياسة `tools.exec` الخاصة بـ gateway، لأن كليهما ما يزال مطبقًا وقت التشغيل
- إذا لم يكن إعداد gateway متاحًا، يعود CLI إلى لقطة موافقات العقدة ويشير إلى أنه تعذّر حساب سياسة وقت التشغيل النهائية
## استبدال الموافقات من ملف
```bash
openclaw approvals set --file ./exec-approvals.json
openclaw approvals set --stdin <<'EOF'
{ version: 1, defaults: { security: "full", ask: "off" } }
EOF
openclaw approvals set --node <id|name|ip> --file ./exec-approvals.json
openclaw approvals set --gateway --file ./exec-approvals.json
```
يقبل `set` تنسيق JSON5، وليس JSON الصارم فقط. استخدم إما `--file` أو `--stdin`، وليس كليهما.
## مثال "عدم السؤال أبدًا" / YOLO
بالنسبة إلى مضيف يجب ألا يتوقف أبدًا عند موافقات exec، اضبط القيم الافتراضية لموافقات المضيف إلى `full` + `off`:
```bash
openclaw approvals set --stdin <<'EOF'
{
version: 1,
defaults: {
security: "full",
ask: "off",
askFallback: "full"
}
}
EOF
```
نسخة العقدة:
```bash
openclaw approvals set --node <id|name|ip> --stdin <<'EOF'
{
version: 1,
defaults: {
security: "full",
ask: "off",
askFallback: "full"
}
}
EOF
```
يغيّر هذا **ملف موافقات المضيف** فقط. ولإبقاء سياسة OpenClaw المطلوبة متوافقة، اضبط أيضًا:
```bash
openclaw config set tools.exec.host gateway
openclaw config set tools.exec.security full
openclaw config set tools.exec.ask off
```
سبب استخدام `tools.exec.host=gateway` في هذا المثال:
- ما يزال `host=auto` يعني "sandbox عند توفره، وإلا فـ gateway".
- يتعلق YOLO بالموافقات، وليس بالتوجيه.
- إذا كنت تريد exec على المضيف حتى عند تكوين sandbox، فاجعل اختيار المضيف صريحًا باستخدام `gateway` أو `/exec host=gateway`.
وهذا يطابق سلوك YOLO الافتراضي الحالي للمضيف. شدّده إذا كنت تريد الموافقات.
## مساعدات قائمة السماح
```bash
openclaw approvals allowlist add "~/Projects/**/bin/rg"
openclaw approvals allowlist add --agent main --node <id|name|ip> "/usr/bin/uptime"
openclaw approvals allowlist add --agent "*" "/usr/bin/uname"
openclaw approvals allowlist remove "~/Projects/**/bin/rg"
```
## الخيارات الشائعة
تدعم الأوامر `get` و`set` و`allowlist add|remove` جميعها ما يلي:
- `--node <id|name|ip>`
- `--gateway`
- خيارات RPC المشتركة للعقد: `--url`, `--token`, `--timeout`, `--json`
ملاحظات الاستهداف:
- عدم استخدام أي علامات استهداف يعني ملف الموافقات المحلي على القرص
- `--gateway` يستهدف ملف موافقات مضيف gateway
- `--node` يستهدف مضيف عقدة واحدًا بعد حل المعرّف أو الاسم أو IP أو بادئة المعرّف
كما يدعم `allowlist add|remove` ما يلي:
- `--agent <id>` (القيمة الافتراضية `*`)
## ملاحظات
- يستخدم `--node` محلل الأهداف نفسه الذي يستخدمه `openclaw nodes` (المعرّف أو الاسم أو ip أو بادئة المعرّف).
- القيمة الافتراضية لـ `--agent` هي `"*"`، وتُطبَّق على جميع الوكلاء.
- يجب أن يعلن مضيف العقدة عن `system.execApprovals.get/set` (تطبيق macOS أو مضيف عقدة headless).
- تُخزَّن ملفات الموافقات لكل مضيف في `~/.openclaw/exec-approvals.json`.

91
docs/ar/cli/backup.md Normal file
View File

@ -0,0 +1,91 @@
---
read_when:
- تريد أرشيف نسخ احتياطي أساسيًا للحالة المحلية لـ OpenClaw
- تريد معاينة المسارات التي ستُضمَّن قبل إعادة الضبط أو إلغاء التثبيت
summary: مرجع CLI للأمر `openclaw backup` (إنشاء أرشيفات نسخ احتياطي محلية)
title: backup
x-i18n:
generated_at: "2026-04-05T12:37:48Z"
model: gpt-5.4
provider: openai
source_hash: 700eda8f9eac1cc93a854fa579f128e5e97d4e6dfc0da75b437c0fb2a898a37d
source_path: cli/backup.md
workflow: 15
---
# `openclaw backup`
أنشئ أرشيف نسخ احتياطي محليًا لحالة OpenClaw والتكوين وملفات تعريف المصادقة وبيانات اعتماد القنوات/المزوّدين والجلسات، ومساحات العمل اختياريًا.
```bash
openclaw backup create
openclaw backup create --output ~/Backups
openclaw backup create --dry-run --json
openclaw backup create --verify
openclaw backup create --no-include-workspace
openclaw backup create --only-config
openclaw backup verify ./2026-03-09T00-00-00.000Z-openclaw-backup.tar.gz
```
## ملاحظات
- يتضمن الأرشيف ملف `manifest.json` يحتوي على مسارات المصدر المحلولة وتخطيط الأرشيف.
- يكون الإخراج الافتراضي أرشيف `.tar.gz` مختومًا بطابع زمني في دليل العمل الحالي.
- إذا كان دليل العمل الحالي داخل شجرة مصدر يجري نسخها احتياطيًا، فإن OpenClaw يعود إلى دليلك المنزلي كموقع افتراضي للأرشيف.
- لا يتم أبدًا استبدال ملفات الأرشيف الموجودة.
- تُرفض مسارات الإخراج داخل أشجار المصدر الخاصة بالحالة/مساحة العمل لتجنب تضمين الأرشيف لنفسه.
- يتحقق `openclaw backup verify <archive>` من أن الأرشيف يحتوي على root manifest واحد فقط، ويرفض مسارات الأرشيف بنمط traversal، ويتأكد من وجود كل حمولة معلنة في manifest داخل tarball.
- يشغّل `openclaw backup create --verify` هذا التحقق مباشرةً بعد كتابة الأرشيف.
- يقوم `openclaw backup create --only-config` بنسخ ملف تكوين JSON النشط فقط احتياطيًا.
## ما الذي يُنسخ احتياطيًا
يخطط `openclaw backup create` لمصادر النسخ الاحتياطي من تثبيت OpenClaw المحلي لديك:
- دليل الحالة الذي يعيده محلل الحالة المحلية في OpenClaw، ويكون عادةً `~/.openclaw`
- مسار ملف التكوين النشط
- دليل `credentials/` المحلول عندما يوجد خارج دليل الحالة
- أدلة مساحات العمل المكتشفة من التكوين الحالي، ما لم تمرر `--no-include-workspace`
تكون ملفات تعريف مصادقة النموذج موجودة بالفعل ضمن دليل الحالة تحت
`agents/<agentId>/agent/auth-profiles.json`، لذا فهي تكون عادةً مشمولة ضمن
إدخال النسخ الاحتياطي للحالة.
إذا استخدمت `--only-config`، فإن OpenClaw يتخطى اكتشاف الحالة ودليل بيانات الاعتماد ومساحة العمل، ويؤرشف فقط مسار ملف التكوين النشط.
يقوم OpenClaw بتوحيد المسارات قبل إنشاء الأرشيف. إذا كان التكوين أو دليل
بيانات الاعتماد أو مساحة العمل موجودًا بالفعل داخل دليل الحالة،
فلن يُكرَّر كمصدر نسخ احتياطي منفصل على المستوى الأعلى. يتم
تخطي المسارات المفقودة.
تخزّن حمولة الأرشيف محتويات الملفات من أشجار المصدر تلك، ويسجل `manifest.json` المضمّن مسارات المصدر المطلقة المحلولة بالإضافة إلى تخطيط الأرشيف المستخدم لكل أصل.
## سلوك التكوين غير الصالح
يتجاوز `openclaw backup` عمدًا الفحص التمهيدي العادي للتكوين حتى يظل مفيدًا أثناء الاستعادة. ولأن اكتشاف مساحة العمل يعتمد على تكوين صالح، فإن `openclaw backup create` يفشل الآن سريعًا عندما يكون ملف التكوين موجودًا لكنه غير صالح بينما لا يزال نسخ مساحة العمل الاحتياطي مفعّلًا.
إذا كنت لا تزال تريد نسخة احتياطية جزئية في هذه الحالة، فأعد التشغيل باستخدام:
```bash
openclaw backup create --no-include-workspace
```
هذا يُبقي الحالة والتكوين ودليل بيانات الاعتماد الخارجي ضمن النطاق مع
تخطي اكتشاف مساحة العمل بالكامل.
إذا كنت تحتاج فقط إلى نسخة من ملف التكوين نفسه، فإن `--only-config` يعمل أيضًا عندما يكون التكوين غير صحيح لأنه لا يعتمد على تحليل التكوين لاكتشاف مساحة العمل.
## الحجم والأداء
لا يفرض OpenClaw حدًا أقصى مضمّنًا لحجم النسخة الاحتياطية أو حدًا لحجم كل ملف.
تأتي الحدود العملية من الجهاز المحلي ونظام الملفات الوجهة:
- المساحة المتاحة لكتابة الأرشيف المؤقت بالإضافة إلى الأرشيف النهائي
- الوقت اللازم لاجتياز أشجار مساحات العمل الكبيرة وضغطها في ملف `.tar.gz`
- الوقت اللازم لإعادة فحص الأرشيف إذا استخدمت `openclaw backup create --verify` أو شغّلت `openclaw backup verify`
- سلوك نظام الملفات في مسار الوجهة. يفضّل OpenClaw خطوة نشر عبر hard-link بدون استبدال، ويعود إلى النسخ الحصري عندما لا تكون hard links مدعومة
تكون مساحات العمل الكبيرة عادةً العامل الرئيسي في حجم الأرشيف. إذا كنت تريد نسخة احتياطية أصغر أو أسرع، فاستخدم `--no-include-workspace`.
وللحصول على أصغر أرشيف، استخدم `--only-config`.

240
docs/ar/cli/browser.md Normal file
View File

@ -0,0 +1,240 @@
---
read_when:
- أنت تستخدم `openclaw browser` وتريد أمثلة على المهام الشائعة
- تريد التحكم في متصفح يعمل على جهاز آخر عبر مضيف node
- تريد الاتصال بـ Chrome المحلي المسجل الدخول إليه عبر Chrome MCP
summary: مرجع CLI للأمر `openclaw browser` ‏(دورة الحياة، والملفات الشخصية، وعلامات التبويب، والإجراءات، والحالة، وتصحيح الأخطاء)
title: browser
x-i18n:
generated_at: "2026-04-05T12:37:56Z"
model: gpt-5.4
provider: openai
source_hash: c89a7483dd733863dd8ebd47a14fbb411808ad07daaed515c1270978de9157e7
source_path: cli/browser.md
workflow: 15
---
# `openclaw browser`
أدر سطح التحكم في المتصفح الخاص بـ OpenClaw ونفّذ إجراءات المتصفح (دورة الحياة، والملفات الشخصية، وعلامات التبويب، واللقطات، ولقطات الشاشة، والتنقل، والإدخال، ومحاكاة الحالة، وتصحيح الأخطاء).
ذو صلة:
- أداة المتصفح + API: ‏[أداة المتصفح](/tools/browser)
## العلامات الشائعة
- `--url <gatewayWsUrl>`: عنوان URL لـ Gateway WebSocket ‏(القيمة الافتراضية من التكوين).
- `--token <token>`: رمز Gateway ‏(إذا كان مطلوبًا).
- `--timeout <ms>`: مهلة الطلب (بالمللي ثانية).
- `--expect-final`: انتظار استجابة Gateway نهائية.
- `--browser-profile <name>`: اختيار ملف تعريف متصفح (القيمة الافتراضية من التكوين).
- `--json`: خرج قابل للقراءة آليًا (حيثما كان مدعومًا).
## البدء السريع (محلي)
```bash
openclaw browser profiles
openclaw browser --browser-profile openclaw start
openclaw browser --browser-profile openclaw open https://example.com
openclaw browser --browser-profile openclaw snapshot
```
## دورة الحياة
```bash
openclaw browser status
openclaw browser start
openclaw browser stop
openclaw browser --browser-profile openclaw reset-profile
```
ملاحظات:
- بالنسبة إلى الملفات الشخصية `attachOnly` وCDP البعيدة، فإن `openclaw browser stop` يغلق
جلسة التحكم النشطة ويمسح تجاوزات المحاكاة المؤقتة حتى عندما
لا يكون OpenClaw قد شغّل عملية المتصفح بنفسه.
- بالنسبة إلى الملفات الشخصية المحلية المُدارة، فإن `openclaw browser stop` يوقف
عملية المتصفح التي تم تشغيلها.
## إذا كان الأمر مفقودًا
إذا كان `openclaw browser` أمرًا غير معروف، فتحقق من `plugins.allow` في
`~/.openclaw/openclaw.json`.
عند وجود `plugins.allow`، يجب إدراج plugin المتصفح المضمّن
بشكل صريح:
```json5
{
plugins: {
allow: ["telegram", "browser"],
},
}
```
لا يؤدي `browser.enabled=true` إلى استعادة الأمر الفرعي في CLI عندما
تستبعد قائمة السماح الخاصة بـ plugin العنصر `browser`.
ذو صلة: [أداة المتصفح](/tools/browser#missing-browser-command-or-tool)
## الملفات الشخصية
الملفات الشخصية هي إعدادات توجيه متصفح مسماة. عمليًا:
- `openclaw`: يشغّل أو يتصل بمثيل Chrome مخصص ومدار بواسطة OpenClaw ‏(دليل بيانات مستخدم معزول).
- `user`: يتحكم في جلسة Chrome الحالية المسجل الدخول إليها عبر Chrome DevTools MCP.
- ملفات CDP الشخصية المخصصة: تشير إلى نقطة نهاية CDP محلية أو بعيدة.
```bash
openclaw browser profiles
openclaw browser create-profile --name work --color "#FF5A36"
openclaw browser create-profile --name chrome-live --driver existing-session
openclaw browser create-profile --name remote --cdp-url https://browser-host.example.com
openclaw browser delete-profile --name work
```
استخدم ملفًا شخصيًا محددًا:
```bash
openclaw browser --browser-profile work tabs
```
## علامات التبويب
```bash
openclaw browser tabs
openclaw browser tab new
openclaw browser tab select 2
openclaw browser tab close 2
openclaw browser open https://docs.openclaw.ai
openclaw browser focus <targetId>
openclaw browser close <targetId>
```
## اللقطة / لقطة الشاشة / الإجراءات
اللقطة:
```bash
openclaw browser snapshot
```
لقطة الشاشة:
```bash
openclaw browser screenshot
openclaw browser screenshot --full-page
openclaw browser screenshot --ref e12
```
ملاحظات:
- `--full-page` مخصص لالتقاطات الصفحة فقط؛ ولا يمكن دمجه مع `--ref`
أو `--element`.
- تدعم الملفات الشخصية `existing-session` / `user` لقطات شاشة للصفحة ولقطات `--ref`
من خرج اللقطة، لكنها لا تدعم لقطات CSS ‏`--element`.
التنقل/النقر/الكتابة (أتمتة واجهة مستخدم قائمة على `ref`):
```bash
openclaw browser navigate https://example.com
openclaw browser click <ref>
openclaw browser type <ref> "hello"
openclaw browser press Enter
openclaw browser hover <ref>
openclaw browser scrollintoview <ref>
openclaw browser drag <startRef> <endRef>
openclaw browser select <ref> OptionA OptionB
openclaw browser fill --fields '[{"ref":"1","value":"Ada"}]'
openclaw browser wait --text "Done"
openclaw browser evaluate --fn '(el) => el.textContent' --ref <ref>
```
مساعدات الملفات + مربعات الحوار:
```bash
openclaw browser upload /tmp/openclaw/uploads/file.pdf --ref <ref>
openclaw browser waitfordownload
openclaw browser download <ref> report.pdf
openclaw browser dialog --accept
```
## الحالة والتخزين
منفذ العرض + المحاكاة:
```bash
openclaw browser resize 1280 720
openclaw browser set viewport 1280 720
openclaw browser set offline on
openclaw browser set media dark
openclaw browser set timezone Europe/London
openclaw browser set locale en-GB
openclaw browser set geo 51.5074 -0.1278 --accuracy 25
openclaw browser set device "iPhone 14"
openclaw browser set headers '{"x-test":"1"}'
openclaw browser set credentials myuser mypass
```
ملفات تعريف الارتباط + التخزين:
```bash
openclaw browser cookies
openclaw browser cookies set session abc123 --url https://example.com
openclaw browser cookies clear
openclaw browser storage local get
openclaw browser storage local set token abc123
openclaw browser storage session clear
```
## تصحيح الأخطاء
```bash
openclaw browser console --level error
openclaw browser pdf
openclaw browser responsebody "**/api"
openclaw browser highlight <ref>
openclaw browser errors --clear
openclaw browser requests --filter api
openclaw browser trace start
openclaw browser trace stop --out trace.zip
```
## Chrome الحالي عبر MCP
استخدم ملف التعريف المضمّن `user`، أو أنشئ ملف تعريف `existing-session` خاصًا بك:
```bash
openclaw browser --browser-profile user tabs
openclaw browser create-profile --name chrome-live --driver existing-session
openclaw browser create-profile --name brave-live --driver existing-session --user-data-dir "~/Library/Application Support/BraveSoftware/Brave-Browser"
openclaw browser --browser-profile chrome-live tabs
```
هذا المسار خاص بالمضيف فقط. بالنسبة إلى Docker، أو الخوادم عديمة الواجهة، أو Browserless، أو الإعدادات البعيدة الأخرى، استخدم ملف تعريف CDP بدلًا من ذلك.
القيود الحالية لـ existing-session:
- تستخدم الإجراءات المعتمدة على اللقطات مراجع refs، وليس محددات CSS
- `click` يدعم النقر الأيسر فقط
- `type` لا يدعم `slowly=true`
- `press` لا يدعم `delayMs`
- ترفض `hover` و`scrollintoview` و`drag` و`select` و`fill` و`evaluate`
تجاوزات المهلة لكل استدعاء
- `select` يدعم قيمة واحدة فقط
- `wait --load networkidle` غير مدعوم
- تتطلب عمليات رفع الملفات `--ref` / `--input-ref`، ولا تدعم
CSS ‏`--element`، وتدعم حاليًا ملفًا واحدًا في كل مرة
- لا تدعم ربطات مربعات الحوار `--timeout`
- تدعم لقطات الشاشة التقاطات الصفحة و`--ref`، لكنها لا تدعم CSS ‏`--element`
- ما زالت `responsebody` واعتراض التنزيلات وتصدير PDF والإجراءات المجمعة
تتطلب متصفحًا مُدارًا أو ملف تعريف CDP خامًا
## التحكم في المتصفح عن بُعد (proxy مضيف node)
إذا كان Gateway يعمل على جهاز مختلف عن المتصفح، فشغّل **مضيف node** على الجهاز الذي يحتوي على Chrome/Brave/Edge/Chromium. سيقوم Gateway بتمرير إجراءات المتصفح إلى تلك العقدة (ولا يلزم خادم منفصل للتحكم في المتصفح).
استخدم `gateway.nodes.browser.mode` للتحكم في التوجيه التلقائي و`gateway.nodes.browser.node` لتثبيت عقدة محددة إذا كانت هناك عدة عقد متصلة.
الأمان + الإعداد عن بُعد: [أداة المتصفح](/tools/browser)، [الوصول عن بُعد](/gateway/remote)، [Tailscale](/gateway/tailscale)، [الأمان](/gateway/security)

138
docs/ar/cli/channels.md Normal file
View File

@ -0,0 +1,138 @@
---
read_when:
- تريد إضافة/إزالة حسابات القنوات (WhatsApp/Telegram/Discord/Google Chat/Slack/Mattermost (إضافة)/Signal/iMessage/Matrix)
- تريد التحقق من حالة القناة أو متابعة سجلات القناة
summary: مرجع CLI للأمر `openclaw channels` (الحسابات، والحالة، وتسجيل الدخول/الخروج، والسجلات)
title: channels
x-i18n:
generated_at: "2026-04-05T12:37:59Z"
model: gpt-5.4
provider: openai
source_hash: d0f558fdb5f6ec54e7fdb7a88e5c24c9d2567174341bd3ea87848bce4cba5d29
source_path: cli/channels.md
workflow: 15
---
# `openclaw channels`
إدارة حسابات قنوات الدردشة وحالة وقت التشغيل الخاصة بها على Gateway.
المستندات ذات الصلة:
- أدلة القنوات: [القنوات](/channels/index)
- تهيئة Gateway: [التهيئة](/gateway/configuration)
## الأوامر الشائعة
```bash
openclaw channels list
openclaw channels status
openclaw channels capabilities
openclaw channels capabilities --channel discord --target channel:123
openclaw channels resolve --channel slack "#general" "@jane"
openclaw channels logs --channel all
```
## الحالة / الإمكانات / الحل / السجلات
- `channels status`: ‏`--probe`، ‏`--timeout <ms>`، ‏`--json`
- `channels capabilities`: ‏`--channel <name>`، ‏`--account <id>` (فقط مع `--channel`)، ‏`--target <dest>`، ‏`--timeout <ms>`، ‏`--json`
- `channels resolve`: ‏`<entries...>`، ‏`--channel <name>`، ‏`--account <id>`، ‏`--kind <auto|user|group>`، ‏`--json`
- `channels logs`: ‏`--channel <name|all>`، ‏`--lines <n>`، ‏`--json`
يُعد `channels status --probe` هو المسار الحي: عند الوصول إلى gateway، فإنه يشغّل
عمليات تحقق `probeAccount` لكل حساب وعمليات `auditAccount` الاختيارية، لذلك قد يتضمن الإخراج
حالة النقل بالإضافة إلى نتائج الفحص مثل `works` أو `probe failed` أو `audit ok` أو `audit failed`.
إذا تعذر الوصول إلى gateway، يعود `channels status` إلى الملخصات المعتمدة على التهيئة فقط
بدلًا من إخراج الفحص الحي.
## إضافة / إزالة الحسابات
```bash
openclaw channels add --channel telegram --token <bot-token>
openclaw channels add --channel nostr --private-key "$NOSTR_PRIVATE_KEY"
openclaw channels remove --channel telegram --delete
```
نصيحة: يعرض `openclaw channels add --help` الوسائط الخاصة بكل قناة (الرمز المميز، والمفتاح الخاص، ورمز التطبيق، ومسارات signal-cli، وما إلى ذلك).
تتضمن أسطح الإضافة الشائعة غير التفاعلية ما يلي:
- قنوات bot-token: ‏`--token`، ‏`--bot-token`، ‏`--app-token`، ‏`--token-file`
- حقول النقل لـ Signal/iMessage: ‏`--signal-number`، ‏`--cli-path`، ‏`--http-url`، ‏`--http-host`، ‏`--http-port`، ‏`--db-path`، ‏`--service`، ‏`--region`
- حقول Google Chat: ‏`--webhook-path`، ‏`--webhook-url`، ‏`--audience-type`، ‏`--audience`
- حقول Matrix: ‏`--homeserver`، ‏`--user-id`، ‏`--access-token`، ‏`--password`، ‏`--device-name`، ‏`--initial-sync-limit`
- حقول Nostr: ‏`--private-key`، ‏`--relay-urls`
- حقول Tlon: ‏`--ship`، ‏`--url`، ‏`--code`، ‏`--group-channels`، ‏`--dm-allowlist`، ‏`--auto-discover-channels`
- ‏`--use-env` للمصادقة المعتمدة على env للحساب الافتراضي عندما تكون مدعومة
عند تشغيل `openclaw channels add` من دون وسائط، يمكن للمعالج التفاعلي أن يطلب:
- معرّفات الحسابات لكل قناة محددة
- أسماء عرض اختيارية لتلك الحسابات
- ‏`Bind configured channel accounts to agents now?`
إذا أكدت الربط الآن، يسأل المعالج عن الوكيل الذي يجب أن يملك كل حساب قناة مهيأ ويكتب روابط توجيه ضمن نطاق الحساب.
يمكنك أيضًا إدارة قواعد التوجيه نفسها لاحقًا باستخدام `openclaw agents bindings` و`openclaw agents bind` و`openclaw agents unbind` (راجع [agents](/cli/agents)).
عند إضافة حساب غير افتراضي إلى قناة ما تزال تستخدم إعدادات المستوى الأعلى لحساب واحد، يقوم OpenClaw بترقية القيم ذات النطاق الحسابي في المستوى الأعلى إلى خريطة حسابات القناة قبل كتابة الحساب الجديد. تضع معظم القنوات تلك القيم في `channels.<channel>.accounts.default`، لكن القنوات المدمجة يمكنها الحفاظ على حساب مُرقّى مطابق موجود بدلًا من ذلك. Matrix هي المثال الحالي: إذا كان هناك حساب مسمى واحد موجود بالفعل، أو كانت `defaultAccount` تشير إلى حساب مسمى موجود، فإن الترقية تحافظ على ذلك الحساب بدلًا من إنشاء `accounts.default` جديد.
يبقى سلوك التوجيه متسقًا:
- تستمر الروابط الموجودة الخاصة بالقناة فقط (من دون `accountId`) في مطابقة الحساب الافتراضي.
- لا ينشئ `channels add` الروابط أو يعيد كتابتها تلقائيًا في الوضع غير التفاعلي.
- يمكن للإعداد التفاعلي اختياريًا إضافة روابط ضمن نطاق الحساب.
إذا كانت تهيئتك بالفعل في حالة مختلطة (وجود حسابات مسماة مع بقاء قيم المستوى الأعلى الخاصة بالحساب الواحد مضبوطة)، فشغّل `openclaw doctor --fix` لنقل القيم ذات النطاق الحسابي إلى الحساب المُرقّى المختار لتلك القناة. تقوم معظم القنوات بالترقية إلى `accounts.default`؛ ويمكن لـ Matrix الحفاظ على هدف مسمى/افتراضي موجود بدلًا من ذلك.
## تسجيل الدخول / تسجيل الخروج (تفاعلي)
```bash
openclaw channels login --channel whatsapp
openclaw channels logout --channel whatsapp
```
ملاحظات:
- يدعم `channels login` الخيار `--verbose`.
- يمكن للأمرين `channels login` / `logout` استنتاج القناة عندما يكون هناك هدف تسجيل دخول مدعوم واحد فقط مهيأ.
## استكشاف الأخطاء وإصلاحها
- شغّل `openclaw status --deep` لإجراء فحص واسع.
- استخدم `openclaw doctor` للحصول على إصلاحات إرشادية.
- إذا طبع `openclaw channels list` القيمة `Claude: HTTP 403 ... user:profile` فهذا يعني أن لقطة الاستخدام تحتاج إلى النطاق `user:profile`. استخدم `--no-usage`، أو وفّر مفتاح جلسة claude.ai (`CLAUDE_WEB_SESSION_KEY` / `CLAUDE_WEB_COOKIE`)، أو أعد المصادقة عبر Claude CLI.
- يعود `openclaw channels status` إلى الملخصات المعتمدة على التهيئة فقط عندما يتعذر الوصول إلى gateway. إذا كانت بيانات اعتماد قناة مدعومة مهيأة عبر SecretRef لكنها غير متاحة في مسار الأمر الحالي، فإنه يبلّغ عن ذلك الحساب على أنه مهيأ مع ملاحظات متدهورة بدلًا من إظهاره على أنه غير مهيأ.
## فحص الإمكانات
اجلب تلميحات إمكانات الموفّر (intents/scopes عند توفرها) بالإضافة إلى دعم الميزات الثابتة:
```bash
openclaw channels capabilities
openclaw channels capabilities --channel discord --target channel:123
```
ملاحظات:
- `--channel` اختياري؛ احذفه لإدراج كل قناة (بما في ذلك الإضافات).
- يكون `--account` صالحًا فقط مع `--channel`.
- يقبل `--target` القيمة `channel:<id>` أو معرّف قناة رقمي خام، وينطبق فقط على Discord.
- تكون عمليات الفحص خاصة بالموفّر: Discord intents + أذونات القناة الاختيارية؛ Slack bot + user scopes؛ Telegram bot flags + webhook؛ Signal daemon version؛ Microsoft Teams app token + Graph roles/scopes (مع تعليقات توضيحية عند المعرفة). أما القنوات التي لا تحتوي على فحوصات فتبلّغ `Probe: unavailable`.
## حل الأسماء إلى معرّفات
حل أسماء القنوات/المستخدمين إلى معرّفات باستخدام دليل الموفّر:
```bash
openclaw channels resolve --channel slack "#general" "@jane"
openclaw channels resolve --channel discord "My Server/#support" "@someone"
openclaw channels resolve --channel matrix "Project Room"
```
ملاحظات:
- استخدم `--kind user|group|auto` لفرض نوع الهدف.
- يفضّل الحل المطابقات النشطة عندما تتشارك عدة إدخالات الاسم نفسه.
- يكون `channels resolve` للقراءة فقط. إذا كان الحساب المحدد مهيأ عبر SecretRef لكن بيانات الاعتماد تلك غير متاحة في مسار الأمر الحالي، فإن الأمر يعيد نتائج غير محلولة متدهورة مع ملاحظات بدلًا من إلغاء التشغيل بالكامل.

28
docs/ar/cli/clawbot.md Normal file
View File

@ -0,0 +1,28 @@
---
read_when:
- أنت تصون نصوصًا أقدم تستخدم `openclaw clawbot ...`
- تحتاج إلى إرشادات الترحيل إلى الأوامر الحالية
summary: مرجع CLI للأمر `openclaw clawbot` (مساحة اسم بديلة قديمة)
title: clawbot
x-i18n:
generated_at: "2026-04-05T12:37:44Z"
model: gpt-5.4
provider: openai
source_hash: 1db82065ecb0107d1ab1a2c6ddaee9df1dd02b983ca1f759974c9d73f0ee3bde
source_path: cli/clawbot.md
workflow: 15
---
# `openclaw clawbot`
مساحة اسم بديلة قديمة أُبقي عليها للتوافق مع الإصدارات السابقة.
الاسم البديل المدعوم حاليًا:
- `openclaw clawbot qr` (السلوك نفسه مثل [`openclaw qr`](/cli/qr))
## الترحيل
يُفضَّل استخدام الأوامر الحديثة ذات المستوى الأعلى مباشرةً:
- `openclaw clawbot qr` -> `openclaw qr`

42
docs/ar/cli/completion.md Normal file
View File

@ -0,0 +1,42 @@
---
read_when:
- أنت تريد إكمالات للصدفة zsh/bash/fish/PowerShell
- تحتاج إلى تخزين برامج الإكمال النصية مؤقتًا ضمن حالة OpenClaw
summary: مرجع CLI للأمر `openclaw completion` (إنشاء/تثبيت برامج الإكمال النصية للصدفة)
title: completion
x-i18n:
generated_at: "2026-04-05T12:37:57Z"
model: gpt-5.4
provider: openai
source_hash: 7bbf140a880bafdb7140149f85465d66d0d46e5a3da6a1e41fb78be2fd2bd4d0
source_path: cli/completion.md
workflow: 15
---
# `openclaw completion`
أنشئ برامج الإكمال النصية للصدفة، ويمكنك اختياريًا تثبيتها في ملف تعريف الصدفة الخاص بك.
## الاستخدام
```bash
openclaw completion
openclaw completion --shell zsh
openclaw completion --install
openclaw completion --shell fish --install
openclaw completion --write-state
openclaw completion --shell bash --write-state
```
## الخيارات
- `-s, --shell <shell>`: هدف الصدفة (`zsh` أو `bash` أو `powershell` أو `fish`؛ الافتراضي: `zsh`)
- `-i, --install`: تثبيت الإكمال عبر إضافة سطر source إلى ملف تعريف الصدفة الخاص بك
- `--write-state`: كتابة برنامج/برامج الإكمال النصية إلى `$OPENCLAW_STATE_DIR/completions` دون الطباعة إلى stdout
- `-y, --yes`: تخطي مطالبات تأكيد التثبيت
## ملاحظات
- يكتب `--install` كتلة صغيرة باسم "OpenClaw Completion" في ملف تعريف الصدفة الخاص بك ويوجهها إلى البرنامج النصي المخزن مؤقتًا.
- من دون `--install` أو `--write-state`، يطبع الأمر البرنامج النصي إلى stdout.
- يقوم إنشاء الإكمال بتحميل أشجار الأوامر مسبقًا بحيث يتم تضمين الأوامر الفرعية المتداخلة.

360
docs/ar/cli/config.md Normal file
View File

@ -0,0 +1,360 @@
---
read_when:
- تريد قراءة الإعداد أو تعديله دون تفاعل
summary: مرجع CLI للأمر `openclaw config` ‏(get/set/unset/file/schema/validate)
title: config
x-i18n:
generated_at: "2026-04-05T12:38:18Z"
model: gpt-5.4
provider: openai
source_hash: e4de30f41e15297019151ad1a5b306cb331fd5c2beefd5ce5b98fcc51e95f0de
source_path: cli/config.md
workflow: 15
---
# `openclaw config`
مساعدات الإعداد لإجراء تعديلات غير تفاعلية في `openclaw.json`: أوامر get/set/unset/file/schema/validate
للقيم حسب المسار وطباعة ملف الإعداد النشط. شغّل الأمر من دون أمر فرعي لفتح
معالج الإعداد (وهو نفسه `openclaw configure`).
خيارات الجذر:
- `--section <section>`: عامل تصفية قابل للتكرار لأقسام الإعداد الموجّه عند تشغيل `openclaw config` من دون أمر فرعي
الأقسام الموجّهة المدعومة:
- `workspace`
- `model`
- `web`
- `gateway`
- `daemon`
- `channels`
- `plugins`
- `skills`
- `health`
## أمثلة
```bash
openclaw config file
openclaw config --section model
openclaw config --section gateway --section daemon
openclaw config schema
openclaw config get browser.executablePath
openclaw config set browser.executablePath "/usr/bin/google-chrome"
openclaw config set agents.defaults.heartbeat.every "2h"
openclaw config set agents.list[0].tools.exec.node "node-id-or-name"
openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN
openclaw config set secrets.providers.vaultfile --provider-source file --provider-path /etc/openclaw/secrets.json --provider-mode json
openclaw config unset plugins.entries.brave.config.webSearch.apiKey
openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN --dry-run
openclaw config validate
openclaw config validate --json
```
### `config schema`
يطبع JSON schema المُولَّد لملف `openclaw.json` إلى stdout بصيغة JSON.
ما الذي يتضمنه:
- schema إعداد الجذر الحالية، بالإضافة إلى حقل سلسلة `$schema` على مستوى الجذر لأدوات المحرر
- بيانات التوثيق الوصفية للحقلين `title` و`description` المستخدمة بواسطة Control UI
- ترث العقد الخاصة بالكائنات المتداخلة، والرمز الشامل (`*`)، وعناصر المصفوفات (`[]`) بيانات `title` / `description` الوصفية نفسها عندما تتوفر وثائق حقول مطابقة
- كما ترث فروع `anyOf` / `oneOf` / `allOf` بيانات التوثيق الوصفية نفسها عندما تتوفر وثائق حقول مطابقة
- بيانات schema وصفية مباشرة لأفضل جهد للإضافات + القنوات عندما يمكن تحميل manifests وقت التشغيل
- schema احتياطية نظيفة حتى عندما يكون الإعداد الحالي غير صالح
RPC وقت التشغيل ذو الصلة:
- يعيد `config.schema.lookup` مسار إعداد واحدًا مُطبَّعًا مع عقدة
schema سطحية (`title`, `description`, `type`, `enum`, `const`, والحدود الشائعة)،
وبيانات وصفية مطابقة لتلميحات واجهة المستخدم، وملخصات الأبناء المباشرين. استخدمه
للاستكشاف الموجّه بالمسار في Control UI أو في العملاء المخصصين.
```bash
openclaw config schema
```
مرّره إلى ملف عندما تريد فحصه أو التحقق منه بأدوات أخرى:
```bash
openclaw config schema > openclaw.schema.json
```
### المسارات
تستخدم المسارات صيغة النقطة أو الأقواس:
```bash
openclaw config get agents.defaults.workspace
openclaw config get agents.list[0].id
```
استخدم فهرس قائمة الوكلاء لاستهداف وكيل محدد:
```bash
openclaw config get agents.list
openclaw config set agents.list[1].tools.exec.node "node-id-or-name"
```
## القيم
تُحلَّل القيم بصيغة JSON5 عند الإمكان؛ وإلا تُعامل كسلاسل نصية.
استخدم `--strict-json` لفرض تحليل JSON5. وما يزال `--json` مدعومًا كاسم بديل قديم.
```bash
openclaw config set agents.defaults.heartbeat.every "0m"
openclaw config set gateway.port 19001 --strict-json
openclaw config set channels.whatsapp.groups '["*"]' --strict-json
```
يطبع `config get <path> --json` القيمة الخام بصيغة JSON بدلًا من النص المنسق للطرفية.
## أوضاع `config set`
يدعم `openclaw config set` أربعة أنماط للإسناد:
1. وضع القيمة: `openclaw config set <path> <value>`
2. وضع منشئ SecretRef:
```bash
openclaw config set channels.discord.token \
--ref-provider default \
--ref-source env \
--ref-id DISCORD_BOT_TOKEN
```
3. وضع منشئ المزوّد (للمسار `secrets.providers.<alias>` فقط):
```bash
openclaw config set secrets.providers.vault \
--provider-source exec \
--provider-command /usr/local/bin/openclaw-vault \
--provider-arg read \
--provider-arg openai/api-key \
--provider-timeout-ms 5000
```
4. وضع الدُفعات (`--batch-json` أو `--batch-file`):
```bash
openclaw config set --batch-json '[
{
"path": "secrets.providers.default",
"provider": { "source": "env" }
},
{
"path": "channels.discord.token",
"ref": { "source": "env", "provider": "default", "id": "DISCORD_BOT_TOKEN" }
}
]'
```
```bash
openclaw config set --batch-file ./config-set.batch.json --dry-run
```
ملاحظة حول السياسة:
- تُرفض إسنادات SecretRef على الأسطح غير المدعومة القابلة للتغيير وقت التشغيل (مثل `hooks.token` و`commands.ownerDisplaySecret` وwebhook tokens الخاصة بربط سلاسل Discord وWhatsApp creds JSON). راجع [SecretRef Credential Surface](/reference/secretref-credential-surface).
يستخدم تحليل الدُفعات دائمًا حمولة الدُفعة (`--batch-json`/`--batch-file`) بوصفها مصدر الحقيقة.
لا يغيّر `--strict-json` / `--json` سلوك تحليل الدُفعات.
ما يزال وضع مسار/قيمة JSON مدعومًا لكل من SecretRefs والمزوّدات:
```bash
openclaw config set channels.discord.token \
'{"source":"env","provider":"default","id":"DISCORD_BOT_TOKEN"}' \
--strict-json
openclaw config set secrets.providers.vaultfile \
'{"source":"file","path":"/etc/openclaw/secrets.json","mode":"json"}' \
--strict-json
```
## علامات منشئ المزوّد
يجب أن تستخدم أهداف منشئ المزوّد `secrets.providers.<alias>` كمسار.
العلامات الشائعة:
- `--provider-source <env|file|exec>`
- `--provider-timeout-ms <ms>` ‏(`file`, `exec`)
مزوّد env ‏(`--provider-source env`):
- `--provider-allowlist <ENV_VAR>` (قابلة للتكرار)
مزوّد file ‏(`--provider-source file`):
- `--provider-path <path>` (مطلوب)
- `--provider-mode <singleValue|json>`
- `--provider-max-bytes <bytes>`
مزوّد exec ‏(`--provider-source exec`):
- `--provider-command <path>` (مطلوب)
- `--provider-arg <arg>` (قابلة للتكرار)
- `--provider-no-output-timeout-ms <ms>`
- `--provider-max-output-bytes <bytes>`
- `--provider-json-only`
- `--provider-env <KEY=VALUE>` (قابلة للتكرار)
- `--provider-pass-env <ENV_VAR>` (قابلة للتكرار)
- `--provider-trusted-dir <path>` (قابلة للتكرار)
- `--provider-allow-insecure-path`
- `--provider-allow-symlink-command`
مثال لمزوّد exec مُقوّى:
```bash
openclaw config set secrets.providers.vault \
--provider-source exec \
--provider-command /usr/local/bin/openclaw-vault \
--provider-arg read \
--provider-arg openai/api-key \
--provider-json-only \
--provider-pass-env VAULT_TOKEN \
--provider-trusted-dir /usr/local/bin \
--provider-timeout-ms 5000
```
## التشغيل التجريبي
استخدم `--dry-run` للتحقق من التغييرات من دون الكتابة إلى `openclaw.json`.
```bash
openclaw config set channels.discord.token \
--ref-provider default \
--ref-source env \
--ref-id DISCORD_BOT_TOKEN \
--dry-run
openclaw config set channels.discord.token \
--ref-provider default \
--ref-source env \
--ref-id DISCORD_BOT_TOKEN \
--dry-run \
--json
openclaw config set channels.discord.token \
--ref-provider vault \
--ref-source exec \
--ref-id discord/token \
--dry-run \
--allow-exec
```
سلوك التشغيل التجريبي:
- وضع المنشئ: يشغّل فحوصات قابلية حل SecretRef للمراجع/المزوّدات المتغيرة.
- وضع JSON ‏(`--strict-json` أو `--json` أو وضع الدُفعات): يشغّل التحقق من schema بالإضافة إلى فحوصات قابلية حل SecretRef.
- يجري أيضًا التحقق من السياسة للأسطح المعروفة غير المدعومة كأهداف SecretRef.
- تقيّم فحوصات السياسة كامل الإعداد بعد التغيير، لذلك لا يمكن لعمليات الكتابة على الكائن الأب (مثل ضبط `hooks` ككائن) تجاوز التحقق من الأسطح غير المدعومة.
- تُتخطى فحوصات SecretRef الخاصة بـ exec افتراضيًا أثناء التشغيل التجريبي لتجنب الآثار الجانبية للأوامر.
- استخدم `--allow-exec` مع `--dry-run` للاشتراك في فحوصات SecretRef الخاصة بـ exec (قد يؤدي هذا إلى تنفيذ أوامر المزوّد).
- `--allow-exec` مخصص للتشغيل التجريبي فقط ويُرجع خطأ إذا استُخدم من دون `--dry-run`.
يطبع `--dry-run --json` تقريرًا قابلًا للقراءة آليًا:
- `ok`: ما إذا نجح التشغيل التجريبي
- `operations`: عدد الإسنادات التي جرى تقييمها
- `checks`: ما إذا شُغِّلت فحوصات schema/قابلية الحل
- `checks.resolvabilityComplete`: ما إذا اكتملت فحوصات قابلية الحل (تكون false عند تخطي مراجع exec)
- `refsChecked`: عدد المراجع التي جرى حلها فعليًا أثناء التشغيل التجريبي
- `skippedExecRefs`: عدد مراجع exec التي جرى تخطيها لأن `--allow-exec` لم يُضبط
- `errors`: إخفاقات schema/قابلية الحل المنظمة عندما تكون `ok=false`
### شكل خرج JSON
```json5
{
ok: boolean,
operations: number,
configPath: string,
inputModes: ["value" | "json" | "builder", ...],
checks: {
schema: boolean,
resolvability: boolean,
resolvabilityComplete: boolean,
},
refsChecked: number,
skippedExecRefs: number,
errors?: [
{
kind: "schema" | "resolvability",
message: string,
ref?: string, // present for resolvability errors
},
],
}
```
مثال نجاح:
```json
{
"ok": true,
"operations": 1,
"configPath": "~/.openclaw/openclaw.json",
"inputModes": ["builder"],
"checks": {
"schema": false,
"resolvability": true,
"resolvabilityComplete": true
},
"refsChecked": 1,
"skippedExecRefs": 0
}
```
مثال فشل:
```json
{
"ok": false,
"operations": 1,
"configPath": "~/.openclaw/openclaw.json",
"inputModes": ["builder"],
"checks": {
"schema": false,
"resolvability": true,
"resolvabilityComplete": true
},
"refsChecked": 1,
"skippedExecRefs": 0,
"errors": [
{
"kind": "resolvability",
"message": "Error: Environment variable \"MISSING_TEST_SECRET\" is not set.",
"ref": "env:default:MISSING_TEST_SECRET"
}
]
}
```
إذا فشل التشغيل التجريبي:
- `config schema validation failed`: شكل الإعداد بعد التغيير غير صالح؛ أصلح شكل المسار/القيمة أو كائن المزوّد/المرجع.
- `Config policy validation failed: unsupported SecretRef usage`: أعد بيانات الاعتماد هذه إلى إدخال نصي عادي/سلسلة نصية، وأبقِ SecretRefs على الأسطح المدعومة فقط.
- `SecretRef assignment(s) could not be resolved`: لا يمكن حاليًا حل المزوّد/المرجع المشار إليه (متغير env مفقود، أو مؤشر ملف غير صالح، أو فشل مزوّد exec، أو عدم تطابق المزوّد/المصدر).
- `Dry run note: skipped <n> exec SecretRef resolvability check(s)`: تخطى التشغيل التجريبي مراجع exec؛ أعد التشغيل مع `--allow-exec` إذا كنت تحتاج إلى التحقق من قابلية حل exec.
- في وضع الدُفعات، أصلح الإدخالات الفاشلة وأعد تشغيل `--dry-run` قبل الكتابة.
## الأوامر الفرعية
- `config file`: يطبع مسار ملف الإعداد النشط (المحلول من `OPENCLAW_CONFIG_PATH` أو من الموقع الافتراضي).
أعد تشغيل gateway بعد التعديلات.
## التحقق
تحقق من الإعداد الحالي مقابل schema النشطة من دون بدء
gateway.
```bash
openclaw config validate
openclaw config validate --json
```

76
docs/ar/cli/configure.md Normal file
View File

@ -0,0 +1,76 @@
---
read_when:
- أنت تريد تعديل بيانات الاعتماد أو الأجهزة أو الإعدادات الافتراضية للوكيل بشكل تفاعلي
summary: مرجع CLI للأمر `openclaw configure` ‏(مطالبات الإعداد التفاعلية)
title: configure
x-i18n:
generated_at: "2026-04-05T12:37:58Z"
model: gpt-5.4
provider: openai
source_hash: 989569fdb8e1b31ce3438756b3ed9bf18e0c8baf611c5981643ba5925459c98f
source_path: cli/configure.md
workflow: 15
---
# `openclaw configure`
مطالبة تفاعلية لإعداد بيانات الاعتماد والأجهزة والإعدادات الافتراضية للوكيل.
ملاحظة: يتضمن قسم **Model** الآن اختيارًا متعددًا لقائمة السماح
`agents.defaults.models` ‏(ما يظهر في `/model` وفي منتقي النموذج).
عندما يبدأ configure من اختيار مصادقة مزوّد، فإن منتقيات النموذج الافتراضي
وقائمة السماح تفضّل ذلك المزوّد تلقائيًا. وبالنسبة إلى المزوّدين المقترنين مثل
Volcengine/BytePlus، فإن التفضيل نفسه يطابق أيضًا متغيرات خطة البرمجة الخاصة بهم
(`volcengine-plan/*` و`byteplus-plan/*`). وإذا كان عامل تصفية
المزوّد المفضّل سينتج قائمة فارغة، فإن configure يعود إلى الفهرس غير المصفّى
بدلًا من إظهار منتقٍ فارغ.
نصيحة: يؤدي تشغيل `openclaw config` من دون أمر فرعي إلى فتح المعالج نفسه. استخدم
`openclaw config get|set|unset` للتعديلات غير التفاعلية.
بالنسبة إلى البحث على الويب، يتيح لك `openclaw configure --section web` اختيار مزوّد
وتهيئة بيانات اعتماده. وتعرض بعض المزوّدات أيضًا مطالبات متابعة خاصة بالمزوّد:
- يمكن لـ **Grok** أن يقدّم إعداد `x_search` اختياريًا باستخدام `XAI_API_KEY` نفسه
ويتيح لك اختيار نموذج `x_search`.
- يمكن لـ **Kimi** أن يطلب منطقة Moonshot API ‏(`api.moonshot.ai` مقابل
`api.moonshot.cn`) ونموذج البحث على الويب الافتراضي لـ Kimi.
ذو صلة:
- مرجع إعدادات Gateway: [Configuration](/gateway/configuration)
- Config CLI: [Config](/cli/config)
## الخيارات
- `--section <section>`: عامل تصفية للأقسام قابل للتكرار
الأقسام المتاحة:
- `workspace`
- `model`
- `web`
- `gateway`
- `daemon`
- `channels`
- `plugins`
- `skills`
- `health`
ملاحظات:
- يؤدي اختيار مكان تشغيل Gateway دائمًا إلى تحديث `gateway.mode`. ويمكنك اختيار "Continue" من دون أقسام أخرى إذا كان هذا كل ما تحتاج إليه.
- تطلب الخدمات الموجهة للقنوات (Slack/Discord/Matrix/Microsoft Teams) قوائم سماح للقنوات/الغرف أثناء الإعداد. ويمكنك إدخال الأسماء أو المعرّفات؛ ويحاول المعالج تحويل الأسماء إلى معرّفات عندما يكون ذلك ممكنًا.
- إذا شغّلت خطوة تثبيت daemon، فإن مصادقة الرمز تتطلب رمزًا، وإذا كانت `gateway.auth.token` مُدارة عبر SecretRef، فإن configure يتحقق من SecretRef لكنه لا يحفظ قيم الرمز النصية الصريحة التي تم حلها ضمن بيانات بيئة خدمة المشرف.
- إذا كانت مصادقة الرمز تتطلب رمزًا وكان SecretRef المهيأ للرمز غير محلول، فإن configure يحظر تثبيت daemon مع إرشادات معالجة واضحة.
- إذا كان كل من `gateway.auth.token` و`gateway.auth.password` مهيأين وكانت `gateway.auth.mode` غير مضبوطة، فإن configure يحظر تثبيت daemon حتى يتم ضبط الوضع صراحةً.
## أمثلة
```bash
openclaw configure
openclaw configure --section web
openclaw configure --section model --section channels
openclaw configure --section gateway --section daemon
```

173
docs/ar/cli/cron.md Normal file
View File

@ -0,0 +1,173 @@
---
read_when:
- تريد مهام مجدولة وعمليات إيقاظ
- أنت تصحح تنفيذ cron والسجلات الخاصة به
summary: مرجع CLI للأمر `openclaw cron` (جدولة المهام الخلفية وتشغيلها)
title: cron
x-i18n:
generated_at: "2026-04-05T12:38:16Z"
model: gpt-5.4
provider: openai
source_hash: f74ec8847835f24b3970f1b260feeb69c7ab6c6ec7e41615cbb73f37f14a8112
source_path: cli/cron.md
workflow: 15
---
# `openclaw cron`
إدارة مهام cron لجدولة Gateway.
ذو صلة:
- مهام Cron: [Cron jobs](/automation/cron-jobs)
نصيحة: شغّل `openclaw cron --help` للحصول على سطح الأوامر الكامل.
ملاحظة: تستخدم مهام `cron add` المعزولة التسليم عبر `--announce` افتراضيًا. استخدم `--no-deliver` للإبقاء على
المخرجات داخلية. لا يزال `--deliver` متاحًا كاسم مستعار متروك لـ `--announce`.
ملاحظة: تتوقع العمليات المعزولة المملوكة لـ cron ملخصًا بنص عادي، ويتولى المشغّل
مسار الإرسال النهائي. يُبقي `--no-deliver` التشغيل داخليًا؛ ولا يعيد
التسليم إلى أداة رسائل الوكيل.
ملاحظة: تُحذف المهام ذات التشغيل الواحد (`--at`) بعد النجاح افتراضيًا. استخدم `--keep-after-run` للاحتفاظ بها.
ملاحظة: يدعم `--session` القيم `main` و`isolated` و`current` و`session:<id>`.
استخدم `current` للربط بالجلسة النشطة وقت الإنشاء، أو `session:<id>` من أجل
مفتاح جلسة صريح ودائم.
ملاحظة: بالنسبة إلى مهام CLI ذات التشغيل الواحد، تُعامل تواريخ `--at` التي لا تحتوي على إزاحة زمنية على أنها UTC ما لم تمرر أيضًا
`--tz <iana>`، والذي يفسر ذلك الوقت المحلي في المنطقة الزمنية المحددة.
ملاحظة: تستخدم المهام المتكررة الآن تراجع إعادة محاولة أسيًا بعد الأخطاء المتتالية (30 ثانية ← 1 دقيقة ← 5 دقائق ← 15 دقيقة ← 60 دقيقة)، ثم تعود إلى الجدول العادي بعد التشغيل الناجح التالي.
ملاحظة: يعيد `openclaw cron run` الآن التحكم بمجرد وضع التشغيل اليدوي في قائمة التنفيذ. تتضمن الاستجابات الناجحة `{ ok: true, enqueued: true, runId }`؛ استخدم `openclaw cron runs --id <job-id>` لمتابعة النتيجة النهائية.
ملاحظة: يفرض `openclaw cron run <job-id>` التشغيل افتراضيًا. استخدم `--due` للحفاظ على
السلوك الأقدم "شغّل فقط إذا كان مستحقًا".
ملاحظة: تُخفي دورات cron المعزولة الردود القديمة التي تقتصر على الإقرار فقط. إذا كانت
النتيجة الأولى مجرد تحديث حالة مؤقت ولم يكن أي تشغيل لوكيل فرعي تابع
مسؤولًا عن الإجابة النهائية، فإن cron يعيد التوجيه مرة واحدة للحصول على النتيجة الحقيقية
قبل التسليم.
ملاحظة: إذا أعاد تشغيل cron معزول الرمز الصامت فقط (`NO_REPLY` /
`no_reply`)، فإن cron يمنع التسليم الصادر المباشر وكذلك مسار الملخص الاحتياطي
الموضوع في قائمة الانتظار، لذلك لا يتم نشر أي شيء في الدردشة.
ملاحظة: يستخدم `cron add|edit --model ...` ذلك النموذج المسموح المحدد للمهمة.
إذا لم يكن النموذج مسموحًا به، يحذر cron ويعود إلى اختيار نموذج
الوكيل/الافتراضي الخاص بالمهمة بدلًا من ذلك. تظل سلاسل الرجوع الاحتياطي المكوّنة مطبقة،
لكن تجاوز النموذج العادي بدون قائمة رجوع احتياطي صريحة لكل مهمة لم يعد يضيف النموذج الأساسي
للوكيل كهدف إعادة محاولة إضافي مخفي.
ملاحظة: تكون أسبقية نموذج cron المعزول كالتالي: تجاوز Gmail-hook أولًا، ثم
`--model` لكل مهمة، ثم أي تجاوز نموذج مخزن لجلسة cron، ثم اختيار
الوكيل/الافتراضي العادي.
ملاحظة: يتبع الوضع السريع لـ cron المعزول اختيار النموذج المباشر المحلول. يُطبق
تكوين النموذج `params.fastMode` افتراضيًا، لكن تجاوز `fastMode`
المخزن في الجلسة يظل صاحب الأولوية على التكوين.
ملاحظة: إذا ألقى تشغيل معزول الخطأ `LiveSessionModelSwitchError`، فإن cron يحفظ
المزوّد/النموذج المحوّل إليه (وكذلك تجاوز ملف تعريف المصادقة المحوّل عند وجوده) قبل
إعادة المحاولة. تظل حلقة إعادة المحاولة الخارجية محدودة بمحاولتي تبديل بعد
المحاولة الأولية، ثم تتوقف بدلًا من التكرار إلى ما لا نهاية.
ملاحظة: تستخدم إشعارات الفشل `delivery.failureDestination` أولًا، ثم
`cron.failureDestination` العام، ثم تعود في النهاية إلى
هدف الإعلان الأساسي للمهمة عندما لا يكون هناك هدف فشل صريح مكوّن.
ملاحظة: يتم التحكم في الاحتفاظ/التقليم من خلال التكوين:
- `cron.sessionRetention` (الافتراضي `24h`) يزيل جلسات التشغيل المعزولة المكتملة.
- `cron.runLog.maxBytes` + `cron.runLog.keepLines` يزيلان `~/.openclaw/cron/runs/<jobId>.jsonl`.
ملاحظة ترقية: إذا كانت لديك مهام cron أقدم من تنسيق التسليم/التخزين الحالي، فشغّل
`openclaw doctor --fix`. يقوم Doctor الآن بتطبيع حقول cron القديمة (`jobId` و`schedule.cron`،
وحقول التسليم ذات المستوى الأعلى بما في ذلك `threadId` القديم، وأسماء التسليم المستعارة `provider` في الحمولة) ويهجّر
مهام الرجوع الاحتياطي البسيطة لـ webhook ذات `notify: true` إلى تسليم webhook صريح عندما يكون `cron.webhook`
مكوّنًا.
## تعديلات شائعة
حدّث إعدادات التسليم بدون تغيير الرسالة:
```bash
openclaw cron edit <job-id> --announce --channel telegram --to "123456789"
```
تعطيل التسليم لمهمة معزولة:
```bash
openclaw cron edit <job-id> --no-deliver
```
تمكين سياق bootstrap خفيف لمهمة معزولة:
```bash
openclaw cron edit <job-id> --light-context
```
الإعلان إلى قناة محددة:
```bash
openclaw cron edit <job-id> --announce --channel slack --to "channel:C1234567890"
```
إنشاء مهمة معزولة بسياق bootstrap خفيف:
```bash
openclaw cron add \
--name "Lightweight morning brief" \
--cron "0 7 * * *" \
--session isolated \
--message "Summarize overnight updates." \
--light-context \
--no-deliver
```
ينطبق `--light-context` على مهام دورة الوكيل المعزولة فقط. بالنسبة إلى تشغيلات cron، يُبقي الوضع الخفيف سياق bootstrap فارغًا بدلًا من إدخال مجموعة bootstrap الكاملة لمساحة العمل.
ملاحظة حول ملكية التسليم:
- توجّه مهام cron المعزولة المملوكة لـ cron دائمًا التسليم النهائي المرئي للمستخدم من خلال
مشغّل cron (`announce` أو `webhook` أو `none` الداخلي فقط).
- إذا ذكرت المهمة مراسلة مستلم خارجي، فيجب على الوكيل
وصف الوجهة المقصودة في نتيجته بدلًا من محاولة إرسالها مباشرة.
## أوامر إدارية شائعة
تشغيل يدوي:
```bash
openclaw cron run <job-id>
openclaw cron run <job-id> --due
openclaw cron runs --id <job-id> --limit 50
```
إعادة توجيه الوكيل/الجلسة:
```bash
openclaw cron edit <job-id> --agent ops
openclaw cron edit <job-id> --clear-agent
openclaw cron edit <job-id> --session current
openclaw cron edit <job-id> --session "session:daily-brief"
```
تعديلات التسليم:
```bash
openclaw cron edit <job-id> --announce --channel slack --to "channel:C1234567890"
openclaw cron edit <job-id> --best-effort-deliver
openclaw cron edit <job-id> --no-best-effort-deliver
openclaw cron edit <job-id> --no-deliver
```
ملاحظة حول تسليم الإخفاق:
- `delivery.failureDestination` مدعوم للمهام المعزولة.
- لا يمكن لمهام الجلسة الرئيسية استخدام `delivery.failureDestination` إلا عندما يكون
وضع التسليم الأساسي هو `webhook`.
- إذا لم تعيّن أي وجهة فشل وكانت المهمة تعلن بالفعل إلى
قناة، فإن إشعارات الفشل تعيد استخدام هدف الإعلان نفسه.

64
docs/ar/cli/daemon.md Normal file
View File

@ -0,0 +1,64 @@
---
read_when:
- ما زلت تستخدم `openclaw daemon ...` في scripts
- تحتاج إلى أوامر دورة حياة الخدمة (install/start/stop/restart/status)
summary: مرجع CLI للأمر `openclaw daemon` ‏(اسم مستعار قديم لإدارة خدمة gateway)
title: daemon
x-i18n:
generated_at: "2026-04-05T12:38:09Z"
model: gpt-5.4
provider: openai
source_hash: 91fdaf3c4f3e7dd4dff86f9b74a653dcba2674573698cf51efc4890077994169
source_path: cli/daemon.md
workflow: 15
---
# `openclaw daemon`
اسم مستعار قديم لأوامر إدارة خدمة Gateway.
يُطابق `openclaw daemon ...` نفس سطح التحكم في الخدمة الموجود في أوامر خدمة `openclaw gateway ...`.
## الاستخدام
```bash
openclaw daemon status
openclaw daemon install
openclaw daemon start
openclaw daemon stop
openclaw daemon restart
openclaw daemon uninstall
```
## الأوامر الفرعية
- `status`: إظهار حالة تثبيت الخدمة وفحص سلامة Gateway
- `install`: تثبيت الخدمة (`launchd`/`systemd`/`schtasks`)
- `uninstall`: إزالة الخدمة
- `start`: بدء الخدمة
- `stop`: إيقاف الخدمة
- `restart`: إعادة تشغيل الخدمة
## الخيارات الشائعة
- `status`: ‏`--url` و`--token` و`--password` و`--timeout` و`--no-probe` و`--require-rpc` و`--deep` و`--json`
- `install`: ‏`--port` و`--runtime <node|bun>` و`--token` و`--force` و`--json`
- دورة الحياة (`uninstall|start|stop|restart`): ‏`--json`
ملاحظات:
- يقوم `status` بحل `SecretRefs` الخاصة بالمصادقة والمكوّنة لاستخدامها في مصادقة الفحص عندما يكون ذلك ممكنًا.
- إذا تعذر حل `SecretRef` مطلوب للمصادقة في مسار هذا الأمر، فإن `daemon status --json` يبلغ عن `rpc.authWarning` عندما يفشل اتصال/مصادقة الفحص؛ مرّر `--token`/`--password` صراحةً أو قم بحل مصدر السر أولًا.
- إذا نجح الفحص، فسيتم إخفاء تحذيرات auth-ref غير المحلولة لتجنب النتائج الإيجابية الكاذبة.
- يضيف `status --deep` فحصًا على مستوى النظام بأفضل جهد للخدمة. وعندما يعثر على خدمات أخرى شبيهة بـ gateway، يطبع الخرج المخصص للبشر تلميحات للتنظيف ويحذر من أن التوصية المعتادة ما تزال gateway واحدًا لكل جهاز.
- في تثبيتات Linux systemd، تتضمن فحوصات انحراف الرمز في `status` كلاً من مصدري الوحدة `Environment=` و`EnvironmentFile=`.
- تقوم فحوصات الانحراف بحل `SecretRefs` الخاصة بـ `gateway.auth.token` باستخدام بيئة التشغيل المدمجة (بيئة أوامر الخدمة أولًا، ثم بديل بيئة العملية).
- إذا لم تكن مصادقة الرمز فعالة عمليًا (تعيين صريح لـ `gateway.auth.mode` إلى `password`/`none`/`trusted-proxy`، أو عدم تعيين الوضع عندما يمكن أن تفوز كلمة المرور ولا يوجد مرشح رمز يمكن أن يفوز)، فإن فحوصات انحراف الرمز تتخطى حل رمز التكوين.
- عندما تتطلب مصادقة الرمز وجود رمز وتكون `gateway.auth.token` مُدارة عبر SecretRef، فإن `install` يتحقق من أن SecretRef قابلة للحل لكنه لا يحفظ الرمز المحلول في بيانات تعريف بيئة الخدمة.
- إذا كانت مصادقة الرمز تتطلب رمزًا وكان SecretRef المكوَّن للرمز غير قابل للحل، يفشل التثبيت بشكل مغلق.
- إذا تم تكوين كل من `gateway.auth.token` و`gateway.auth.password` وكان `gateway.auth.mode` غير معيّن، فسيتم حظر التثبيت حتى يتم تعيين الوضع صراحةً.
- إذا كنت تشغّل عمدًا عدة بوابات على مضيف واحد، فاعزل المنافذ والتكوين/الحالة ومساحات العمل؛ راجع [/gateway#multiple-gateways-same-host](/gateway#multiple-gateways-same-host).
## المفضّل
استخدم [`openclaw gateway`](/cli/gateway) للحصول على الوثائق والأمثلة الحالية.

29
docs/ar/cli/dashboard.md Normal file
View File

@ -0,0 +1,29 @@
---
read_when:
- أنت تريد فتح واجهة Control UI باستخدام الرمز المميز الحالي الخاص بك
- أنت تريد طباعة عنوان URL دون تشغيل المتصفح
summary: مرجع CLI للأمر `openclaw dashboard` (فتح واجهة Control)
title: dashboard
x-i18n:
generated_at: "2026-04-05T12:38:13Z"
model: gpt-5.4
provider: openai
source_hash: a34cd109a3803e2910fcb4d32f2588aa205a4933819829ef5598f0780f586c94
source_path: cli/dashboard.md
workflow: 15
---
# `openclaw dashboard`
افتح واجهة Control UI باستخدام المصادقة الحالية الخاصة بك.
```bash
openclaw dashboard
openclaw dashboard --no-open
```
ملاحظات:
- يقوم `dashboard` بحل SecretRefs المُعدّة في `gateway.auth.token` عندما يكون ذلك ممكنًا.
- بالنسبة إلى الرموز المميزة المُدارة عبر SecretRef (المحلولة أو غير المحلولة)، يقوم `dashboard` بطباعة/نسخ/فتح عنوان URL غير مضمّن فيه الرمز المميز لتجنب كشف الأسرار الخارجية في مخرجات الطرفية أو سجل الحافظة أو معاملات تشغيل المتصفح.
- إذا كان `gateway.auth.token` مُدارًا عبر SecretRef لكنه غير محلول في مسار هذا الأمر، فسيطبع الأمر عنوان URL غير مضمّن فيه الرمز المميز مع إرشادات معالجة واضحة بدلًا من تضمين عنصر نائب غير صالح للرمز المميز.

178
docs/ar/cli/devices.md Normal file
View File

@ -0,0 +1,178 @@
---
read_when:
- أنت توافق على طلبات اقتران الأجهزة
- تحتاج إلى تدوير رموز الأجهزة أو إلغائها
summary: مرجع CLI للأمر `openclaw devices` ‏(اقتران الأجهزة + تدوير/إلغاء رموز الأجهزة)
title: devices
x-i18n:
generated_at: "2026-04-05T12:38:22Z"
model: gpt-5.4
provider: openai
source_hash: e2f9fcb8e3508a703590f87caaafd953a5d3557e11c958cbb2be1d67bb8720f4
source_path: cli/devices.md
workflow: 15
---
# `openclaw devices`
إدارة طلبات اقتران الأجهزة والرموز المميزة الخاصة بنطاق الجهاز.
## الأوامر
### `openclaw devices list`
يعرض طلبات الاقتران المعلقة والأجهزة المقترنة.
```
openclaw devices list
openclaw devices list --json
```
يتضمن خرج الطلبات المعلقة الدور المطلوب والنطاقات حتى يمكن
مراجعة الموافقات قبل اعتمادها.
### `openclaw devices remove <deviceId>`
إزالة إدخال جهاز مقترن واحد.
عندما تكون مصادقًا باستخدام رمز جهاز مقترن، يمكن للمتصلين غير المشرفين
إزالة إدخال **أجهزتهم فقط**. وتتطلب إزالة جهاز آخر
الصلاحية `operator.admin`.
```
openclaw devices remove <deviceId>
openclaw devices remove <deviceId> --json
```
### `openclaw devices clear --yes [--pending]`
مسح الأجهزة المقترنة بشكل جماعي.
```
openclaw devices clear --yes
openclaw devices clear --yes --pending
openclaw devices clear --yes --pending --json
```
### `openclaw devices approve [requestId] [--latest]`
الموافقة على طلب اقتران جهاز معلق. إذا تم حذف `requestId`، فإن OpenClaw
يوافق تلقائيًا على أحدث طلب معلق.
ملاحظة: إذا أعاد جهاز محاولة الاقتران مع تغيّر في تفاصيل المصادقة (الدور/النطاقات/المفتاح
العام)، فإن OpenClaw يستبدل الإدخال المعلق السابق ويصدر
`requestId` جديدًا. شغّل `openclaw devices list` مباشرة قبل الموافقة لاستخدام
المعرّف الحالي.
```
openclaw devices approve
openclaw devices approve <requestId>
openclaw devices approve --latest
```
### `openclaw devices reject <requestId>`
رفض طلب اقتران جهاز معلق.
```
openclaw devices reject <requestId>
```
### `openclaw devices rotate --device <id> --role <role> [--scope <scope...>]`
تدوير رمز جهاز لدور محدد (مع تحديث النطاقات اختياريًا).
يجب أن يكون الدور المستهدف موجودًا بالفعل ضمن عقد الاقتران المعتمد لذلك الجهاز؛
ولا يمكن للتدوير إنشاء دور جديد غير معتمد.
إذا حذفت `--scope`، فإن عمليات إعادة الاتصال اللاحقة باستخدام الرمز المُدار المخزن تعيد استخدام
النطاقات المعتمدة المخزنة مؤقتًا لذلك الرمز. وإذا مررت قيم `--scope` صريحة، فإنها
تصبح مجموعة النطاقات المخزنة لعمليات إعادة الاتصال المستقبلية باستخدام الرمز المخزن مؤقتًا.
يمكن للمتصلين غير المشرفين من جلسات الأجهزة المقترنة تدوير **رمز أجهزتهم فقط**.
وأيضًا، يجب أن تبقى أي قيم `--scope` صريحة ضمن
نطاقات operator الخاصة بجلسة المتصل نفسها؛ فلا يمكن للتدوير إنشاء رمز operator
أوسع من الذي يملكه المتصل بالفعل.
```
openclaw devices rotate --device <deviceId> --role operator --scope operator.read --scope operator.write
```
يعيد حمولة الرمز الجديد بصيغة JSON.
### `openclaw devices revoke --device <id> --role <role>`
إلغاء رمز جهاز لدور محدد.
يمكن للمتصلين غير المشرفين من الأجهزة المقترنة إلغاء **رمز أجهزتهم فقط**.
أما إلغاء رمز جهاز آخر فيتطلب `operator.admin`.
```
openclaw devices revoke --device <deviceId> --role node
```
يعيد نتيجة الإلغاء بصيغة JSON.
## الخيارات الشائعة
- `--url <url>`: عنوان URL الخاص بـ Gateway WebSocket ‏(يستخدم `gateway.remote.url` افتراضيًا عند إعداده).
- `--token <token>`: رمز Gateway ‏(إذا كان مطلوبًا).
- `--password <password>`: كلمة مرور Gateway ‏(مصادقة كلمة المرور).
- `--timeout <ms>`: مهلة RPC.
- `--json`: خرج JSON ‏(موصى به للبرمجة النصية).
ملاحظة: عند ضبط `--url`، لا يعود CLI إلى بيانات الاعتماد الموجودة في الإعدادات أو البيئة.
مرّر `--token` أو `--password` صراحةً. ويعد غياب بيانات اعتماد صريحة خطأً.
## ملاحظات
- يعيد تدوير الرمز رمزًا جديدًا (حساسًا). تعامل معه على أنه سر.
- تتطلب هذه الأوامر النطاق `operator.pairing` ‏(أو `operator.admin`).
- يبقى تدوير الرمز ضمن مجموعة الأدوار المعتمدة في الاقتران وخط الأساس
المعتمد للنطاقات لذلك الجهاز. ولا يمنح إدخال رمز مخزن مؤقتًا بالخطأ
هدف تدوير جديدًا.
- بالنسبة إلى جلسات رموز الأجهزة المقترنة، تكون الإدارة عبر الأجهزة محصورة بالمشرف:
تكون أوامر `remove` و`rotate` و`revoke` ذاتية فقط ما لم يكن لدى المتصل
`operator.admin`.
- تم تقييد `devices clear` عمدًا بالعلم `--yes`.
- إذا لم يكن نطاق الاقتران متاحًا على local loopback (ولم يتم تمرير `--url` صراحةً)، يمكن للأمرين list/approve استخدام تراجع اقتران محلي.
- يختار `devices approve` أحدث طلب معلق تلقائيًا عندما تحذف `requestId` أو تمرر `--latest`.
## قائمة التحقق من استعادة انحراف الرمز
استخدم هذا عندما يستمر Control UI أو العملاء الآخرون في الفشل مع `AUTH_TOKEN_MISMATCH` أو `AUTH_DEVICE_TOKEN_MISMATCH`.
1. أكّد مصدر رمز gateway الحالي:
```bash
openclaw config get gateway.auth.token
```
2. اعرض الأجهزة المقترنة وحدد معرّف الجهاز المتأثر:
```bash
openclaw devices list
```
3. دوّر رمز operator للجهاز المتأثر:
```bash
openclaw devices rotate --device <deviceId> --role operator
```
4. إذا لم يكن التدوير كافيًا، فأزل الاقتران القديم ووافق من جديد:
```bash
openclaw devices remove <deviceId>
openclaw devices list
openclaw devices approve <requestId>
```
5. أعد محاولة اتصال العميل باستخدام الرمز/كلمة المرور المشتركة الحالية.
ملاحظات:
- تكون أولوية مصادقة إعادة الاتصال العادية هي: الرمز/كلمة المرور المشتركة الصريحة أولًا، ثم `deviceToken` الصريح، ثم رمز الجهاز المخزن، ثم رمز bootstrap.
- يمكن لاستعادة `AUTH_TOKEN_MISMATCH` الموثوقة أن ترسل مؤقتًا كلًا من الرمز المشترك ورمز الجهاز المخزن معًا لتلك إعادة المحاولة الواحدة المحدودة.
ذو صلة:
- [استكشاف مشكلات مصادقة لوحة المعلومات](/web/dashboard#if-you-see-unauthorized-1008)
- [استكشاف مشكلات Gateway وإصلاحها](/gateway/troubleshooting#dashboard-control-ui-connectivity)

70
docs/ar/cli/directory.md Normal file
View File

@ -0,0 +1,70 @@
---
read_when:
- تريد البحث عن معرّفات جهات الاتصال/المجموعات/المعرّف الذاتي لقناة ما
- أنت تطور مهايئ دليل لقناة
summary: مرجع CLI للأمر `openclaw directory` (الذات، والأقران، والمجموعات)
title: directory
x-i18n:
generated_at: "2026-04-05T12:38:08Z"
model: gpt-5.4
provider: openai
source_hash: 6a81a037e0a33f77c24b1adabbc4be16ed4d03c419873f3cbdd63f2ce84a1064
source_path: cli/directory.md
workflow: 15
---
# `openclaw directory`
عمليات بحث الدليل للقنوات التي تدعم ذلك (جهات الاتصال/الأقران، والمجموعات، و"أنا").
## الوسائط الشائعة
- `--channel <name>`: معرّف/اسم مستعار للقناة (مطلوب عند تهيئة عدة قنوات؛ ويُستنتج تلقائيًا عند تهيئة قناة واحدة فقط)
- `--account <id>`: معرّف الحساب (الافتراضي: الحساب الافتراضي للقناة)
- `--json`: إخراج JSON
## ملاحظات
- الغرض من `directory` هو مساعدتك في العثور على المعرّفات التي يمكنك لصقها في أوامر أخرى (وخاصة `openclaw message send --target ...`).
- بالنسبة إلى كثير من القنوات، تكون النتائج مدعومة بالإعداد (قوائم السماح / المجموعات المهيأة) بدلًا من دليل موفّر حي.
- يكون الإخراج الافتراضي هو `id` (وأحيانًا `name`) مفصولًا بعلامة جدولة؛ استخدم `--json` في البرامج النصية.
## استخدام النتائج مع `message send`
```bash
openclaw directory peers list --channel slack --query "U0"
openclaw message send --channel slack --target user:U012ABCDEF --message "hello"
```
## صيغ المعرّفات (حسب القناة)
- WhatsApp: ‏`+15551234567` (رسالة مباشرة)، ‏`1234567890-1234567890@g.us` (مجموعة)
- Telegram: ‏`@username` أو معرّف دردشة رقمي؛ المجموعات هي معرّفات رقمية
- Slack: ‏`user:U…` و`channel:C…`
- Discord: ‏`user:<id>` و`channel:<id>`
- Matrix (إضافة): ‏`user:@user:server` أو `room:!roomId:server` أو `#alias:server`
- Microsoft Teams (إضافة): ‏`user:<id>` و`conversation:<id>`
- Zalo (إضافة): معرّف المستخدم (Bot API)
- Zalo Personal / `zalouser` (إضافة): معرّف سلسلة الرسائل (رسالة مباشرة/مجموعة) من `zca` (`me` و`friend list` و`group list`)
## الذات ("أنا")
```bash
openclaw directory self --channel zalouser
```
## الأقران (جهات الاتصال/المستخدمون)
```bash
openclaw directory peers list --channel zalouser
openclaw directory peers list --channel zalouser --query "name"
openclaw directory peers list --channel zalouser --limit 50
```
## المجموعات
```bash
openclaw directory groups list --channel zalouser
openclaw directory groups list --channel zalouser --query "work"
openclaw directory groups members --channel zalouser --group-id <id>
```

55
docs/ar/cli/dns.md Normal file
View File

@ -0,0 +1,55 @@
---
read_when:
- أنت تريد الاكتشاف عبر النطاق الواسع (DNS-SD) باستخدام Tailscale + CoreDNS
- You’re setting up split DNS for a custom discovery domain (example: openclaw.internal)
summary: مرجع CLI لـ `openclaw dns` (مساعدات الاكتشاف عبر النطاق الواسع)
title: dns
x-i18n:
generated_at: "2026-04-05T12:38:10Z"
model: gpt-5.4
provider: openai
source_hash: 4831fbb7791adfed5195bc4ba36bb248d2bc8830958334211d3c96f824617927
source_path: cli/dns.md
workflow: 15
---
# `openclaw dns`
مساعدات DNS للاكتشاف عبر النطاق الواسع (Tailscale + CoreDNS). وهي تركز حاليًا على macOS + Homebrew CoreDNS.
ذو صلة:
- اكتشاف البوابة: [الاكتشاف](/gateway/discovery)
- إعداد الاكتشاف عبر النطاق الواسع: [الإعداد](/gateway/configuration)
## الإعداد
```bash
openclaw dns setup
openclaw dns setup --domain openclaw.internal
openclaw dns setup --apply
```
## `dns setup`
تخطيط أو تطبيق إعداد CoreDNS لاكتشاف DNS-SD أحادي الإرسال.
الخيارات:
- `--domain <domain>`: نطاق الاكتشاف عبر النطاق الواسع (على سبيل المثال `openclaw.internal`)
- `--apply`: تثبيت أو تحديث إعداد CoreDNS وإعادة تشغيل الخدمة (يتطلب sudo؛ macOS فقط)
ما الذي يعرضه:
- نطاق الاكتشاف الذي تم تحليله
- مسار ملف المنطقة
- عناوين tailnet IP الحالية
- إعداد `openclaw.json` الموصى به للاكتشاف
- قيم nameserver/domain لـ Tailscale Split DNS التي يجب ضبطها
ملاحظات:
- من دون `--apply`، يكون الأمر مجرد مساعد للتخطيط ويطبع الإعداد الموصى به.
- إذا تم حذف `--domain`، يستخدم OpenClaw القيمة `discovery.wideArea.domain` من الإعداد.
- يدعم `--apply` حاليًا macOS فقط ويفترض استخدام Homebrew CoreDNS.
- يقوم `--apply` بتهيئة ملف المنطقة إذا لزم الأمر، ويضمن وجود مقطع import الخاص بـ CoreDNS، ويعيد تشغيل خدمة `coredns` عبر brew.

35
docs/ar/cli/docs.md Normal file
View File

@ -0,0 +1,35 @@
---
read_when:
- تريد البحث في مستندات OpenClaw الحية من الطرفية
summary: مرجع CLI للأمر `openclaw docs` (البحث في فهرس المستندات الحي)
title: docs
x-i18n:
generated_at: "2026-04-05T12:38:11Z"
model: gpt-5.4
provider: openai
source_hash: cfcceed872d7509b9843af3fae733a136bc5e26ded55c2ac47a16489a1636989
source_path: cli/docs.md
workflow: 15
---
# `openclaw docs`
ابحث في فهرس المستندات الحي.
الوسائط:
- `[query...]`: مصطلحات البحث التي سيتم إرسالها إلى فهرس المستندات الحي
أمثلة:
```bash
openclaw docs
openclaw docs browser existing-session
openclaw docs sandbox allowHostControl
openclaw docs gateway token secretref
```
ملاحظات:
- عند عدم تمرير أي استعلام، يفتح `openclaw docs` نقطة دخول البحث في المستندات الحية.
- يتم تمرير الاستعلامات متعددة الكلمات كطلب بحث واحد.

70
docs/ar/cli/doctor.md Normal file
View File

@ -0,0 +1,70 @@
---
read_when:
- لديك مشكلات في الاتصال/المصادقة وتريد إصلاحات موجهة
- قمت بالتحديث وتريد فحصًا سريعًا للتأكد
summary: مرجع CLI للأمر `openclaw doctor` ‏(فحوصات السلامة + إصلاحات موجهة)
title: doctor
x-i18n:
generated_at: "2026-04-05T12:38:21Z"
model: gpt-5.4
provider: openai
source_hash: d257a9e2797b4b0b50c1020165c8a1cd6a2342381bf9c351645ca37494c881e1
source_path: cli/doctor.md
workflow: 15
---
# `openclaw doctor`
فحوصات السلامة + إصلاحات سريعة لـ gateway والقنوات.
ذو صلة:
- استكشاف الأخطاء وإصلاحها: [استكشاف الأخطاء وإصلاحها](/gateway/troubleshooting)
- التدقيق الأمني: [الأمان](/gateway/security)
## أمثلة
```bash
openclaw doctor
openclaw doctor --repair
openclaw doctor --deep
openclaw doctor --repair --non-interactive
openclaw doctor --generate-gateway-token
```
## الخيارات
- `--no-workspace-suggestions`: تعطيل اقتراحات ذاكرة/بحث مساحة العمل
- `--yes`: قبول القيم الافتراضية من دون مطالبة
- `--repair`: تطبيق الإصلاحات الموصى بها من دون مطالبة
- `--fix`: اسم مستعار لـ `--repair`
- `--force`: تطبيق إصلاحات صارمة، بما في ذلك الكتابة فوق تكوين الخدمة المخصص عند الحاجة
- `--non-interactive`: التشغيل من دون مطالبات؛ عمليات ترحيل آمنة فقط
- `--generate-gateway-token`: إنشاء رمز gateway وتكوينه
- `--deep`: فحص خدمات النظام بحثًا عن تثبيتات gateway إضافية
ملاحظات:
- لا تعمل المطالبات التفاعلية (مثل إصلاحات keychain/OAuth) إلا عندما يكون stdin عبارة عن TTY ولا يكون `--non-interactive` مضبوطًا. تتخطى عمليات التشغيل بدون واجهة (cron أو Telegram أو بدون طرفية) المطالبات.
- يقوم `--fix` (الاسم المستعار لـ `--repair`) بكتابة نسخة احتياطية إلى `~/.openclaw/openclaw.json.bak` ويحذف مفاتيح التكوين غير المعروفة مع إدراج كل عملية إزالة.
- تكتشف فحوصات سلامة الحالة الآن ملفات النصوص اليتيمة في دليل الجلسات ويمكنها أرشفتها بصيغة `.deleted.<timestamp>` لاستعادة المساحة بأمان.
- يفحص Doctor أيضًا `~/.openclaw/cron/jobs.json` (أو `cron.store`) بحثًا عن أشكال مهام cron القديمة ويمكنه إعادة كتابتها في مكانها قبل أن يضطر المجدول إلى تطبيعها تلقائيًا في وقت التشغيل.
- يقوم Doctor بترحيل تكوين Talk المسطح القديم تلقائيًا (`talk.voiceId` و`talk.modelId` وما شابه) إلى `talk.provider` + `talk.providers.<provider>`.
- لم تعد عمليات التشغيل المتكررة لـ `doctor --fix` تُبلغ عن/تطبق تطبيع Talk عندما يكون الاختلاف الوحيد هو ترتيب مفاتيح الكائن.
- يتضمن Doctor فحصًا لجهوزية البحث في الذاكرة ويمكنه التوصية باستخدام `openclaw configure --section model` عندما تكون بيانات اعتماد embedding مفقودة.
- إذا كان وضع sandbox ممكّنًا ولكن Docker غير متاح، فإن Doctor يبلغ عن تحذير عالي الإشارة مع المعالجة (`install Docker` أو `openclaw config set agents.defaults.sandbox.mode off`).
- إذا كانت `gateway.auth.token`/`gateway.auth.password` مُدارة عبر SecretRef وغير متاحة في مسار الأمر الحالي، فإن Doctor يبلغ عن تحذير للقراءة فقط ولا يكتب بيانات اعتماد احتياطية بنص واضح.
- إذا فشل فحص SecretRef الخاص بالقناة في مسار الإصلاح، يواصل Doctor العمل ويبلغ عن تحذير بدلًا من الخروج المبكر.
- يتطلب الحل التلقائي لأسماء المستخدمين في Telegram `allowFrom` ‏(`doctor --fix`) رمز Telegram قابلًا للحل في مسار الأمر الحالي. إذا لم يكن فحص الرمز متاحًا، يبلغ Doctor عن تحذير ويتخطى الحل التلقائي في هذه الجولة.
## macOS: تجاوزات بيئة `launchctl`
إذا كنت قد شغّلت سابقًا `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...` (أو `...PASSWORD`)، فإن هذه القيمة تتجاوز ملف التكوين الخاص بك ويمكن أن تسبب أخطاء "unauthorized" مستمرة.
```bash
launchctl getenv OPENCLAW_GATEWAY_TOKEN
launchctl getenv OPENCLAW_GATEWAY_PASSWORD
launchctl unsetenv OPENCLAW_GATEWAY_TOKEN
launchctl unsetenv OPENCLAW_GATEWAY_PASSWORD
```

25
docs/ar/cli/flows.md Normal file
View File

@ -0,0 +1,25 @@
---
read_when:
- تصادف openclaw flows في مستندات أو ملاحظات إصدار أقدم
summary: 'إعادة توجيه: أوامر flow موجودة تحت `openclaw tasks flow`'
title: flows (إعادة توجيه)
x-i18n:
generated_at: "2026-04-05T12:38:13Z"
model: gpt-5.4
provider: openai
source_hash: f4b9acefdb4e8dedde08d96986fe9b1ca7f91293281850b68ff9fa28f0516a61
source_path: cli/flows.md
workflow: 15
---
# `openclaw tasks flow`
أوامر Flow هي أوامر فرعية ضمن `openclaw tasks`، وليست أمر `flows` مستقلًا.
```bash
openclaw tasks flow list [--json]
openclaw tasks flow show <lookup>
openclaw tasks flow cancel <lookup>
```
للحصول على الوثائق الكاملة، راجع [Task Flow](/automation/taskflow) و[مرجع CLI للأمر tasks](/cli/index#tasks).

314
docs/ar/cli/gateway.md Normal file
View File

@ -0,0 +1,314 @@
---
read_when:
- تشغيل Gateway من CLI (للتطوير أو الخوادم)
- تصحيح مصادقة Gateway وأوضاع bind والاتصال
- اكتشاف Gateways عبر Bonjour ‏(local + wide-area DNS-SD)
summary: CLI الخاص بـ OpenClaw Gateway (`openclaw gateway`) — تشغيل Gateways والاستعلام عنها واكتشافها
title: gateway
x-i18n:
generated_at: "2026-04-05T12:38:58Z"
model: gpt-5.4
provider: openai
source_hash: e311ded0dbad84b8212f0968f3563998d49c5e0eb292a0dc4b3bd3c22d4fa7f2
source_path: cli/gateway.md
workflow: 15
---
# CLI الخاص بـ Gateway
Gateway هو خادم WebSocket الخاص بـ OpenClaw (القنوات، والعقد، والجلسات، وhooks).
توجد الأوامر الفرعية في هذه الصفحة تحت `openclaw gateway …`.
المستندات ذات الصلة:
- [/gateway/bonjour](/gateway/bonjour)
- [/gateway/discovery](/gateway/discovery)
- [/gateway/configuration](/gateway/configuration)
## تشغيل Gateway
شغّل عملية Gateway محلية:
```bash
openclaw gateway
```
الاسم المستعار للتشغيل في الواجهة الأمامية:
```bash
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 يتعامل مع ذلك على أنه تلف مريب في التهيئة ويرفض "افتراض local" نيابةً عنك.
- يتم حظر الربط خارج loopback بدون مصادقة (حاجز أمان).
- يؤدي `SIGUSR1` إلى إعادة تشغيل داخل العملية عند السماح بذلك (`commands.restart` مفعّل افتراضيًا؛ اضبط `commands.restart: false` لحظر إعادة التشغيل اليدوية، مع بقاء أداة gateway وتطبيق/تحديث التهيئة مسموحين).
- تؤدي معالجات `SIGINT`/`SIGTERM` إلى إيقاف عملية gateway، لكنها لا تستعيد أي حالة طرفية مخصصة. إذا كنت تغلف CLI بواجهة TUI أو إدخال raw-mode، فاستعد حالة الطرفية قبل الخروج.
### الخيارات
- `--port <port>`: منفذ WebSocket (تأتي القيمة الافتراضية من config/env؛ وعادةً `18789`).
- `--bind <loopback|lan|tailnet|auto|custom>`: وضع ربط المستمع.
- `--auth <token|password>`: تجاوز وضع المصادقة.
- `--token <token>`: تجاوز token (ويضبط أيضًا `OPENCLAW_GATEWAY_TOKEN` للعملية).
- `--password <password>`: تجاوز كلمة المرور. تحذير: قد تظهر كلمات المرور المضمنة في قوائم العمليات المحلية.
- `--password-file <path>`: قراءة كلمة مرور gateway من ملف.
- `--tailscale <off|serve|funnel>`: كشف Gateway عبر Tailscale.
- `--tailscale-reset-on-exit`: إعادة تعيين تهيئة Tailscale serve/funnel عند الإغلاق.
- `--allow-unconfigured`: السماح ببدء gateway دون `gateway.mode=local` في الإعداد. يتجاوز هذا حاجز بدء التشغيل للتمهيد المخصص/التطويري فقط؛ ولا يكتب ملف التهيئة أو يصلحه.
- `--dev`: إنشاء تهيئة + workspace للتطوير إذا كانت مفقودة (يتخطى `BOOTSTRAP.md`).
- `--reset`: إعادة تعيين تهيئة التطوير + بيانات الاعتماد + الجلسات + workspace (يتطلب `--dev`).
- `--force`: إنهاء أي مستمع موجود على المنفذ المحدد قبل البدء.
- `--verbose`: سجلات مفصلة.
- `--cli-backend-logs`: عرض سجلات الواجهة الخلفية لـ CLI فقط في الطرفية (مع تمكين stdout/stderr).
- `--claude-cli-logs`: اسم مستعار مهمل لـ `--cli-backend-logs`.
- `--ws-log <auto|full|compact>`: نمط سجل websocket (الافتراضي `auto`).
- `--compact`: اسم مستعار لـ `--ws-log compact`.
- `--raw-stream`: تسجيل أحداث تدفق النموذج الخام إلى jsonl.
- `--raw-stream-path <path>`: مسار jsonl للتدفق الخام.
## الاستعلام عن Gateway يعمل
تستخدم جميع أوامر الاستعلام WebSocket RPC.
أوضاع الإخراج:
- الافتراضي: قابل للقراءة البشرية (ملون في TTY).
- `--json`: JSON قابل للقراءة آليًا (من دون تنسيق/مؤشر دوران).
- `--no-color` (أو `NO_COLOR=1`): تعطيل ANSI مع إبقاء التخطيط البشري.
الخيارات المشتركة (حيثما كانت مدعومة):
- `--url <url>`: عنوان URL لـ Gateway WebSocket.
- `--token <token>`: token الخاص بـ Gateway.
- `--password <password>`: كلمة مرور Gateway.
- `--timeout <ms>`: المهلة/الميزانية (تختلف حسب الأمر).
- `--expect-final`: انتظار استجابة "نهائية" (استدعاءات الوكيل).
ملاحظة: عندما تضبط `--url`، لا يعود CLI إلى بيانات الاعتماد الموجودة في config أو environment.
مرّر `--token` أو `--password` صراحة. وغياب بيانات اعتماد صريحة يُعد خطأً.
### `gateway health`
```bash
openclaw gateway health --url ws://127.0.0.1:18789
```
### `gateway usage-cost`
اجلب ملخصات تكلفة الاستخدام من سجلات الجلسات.
```bash
openclaw gateway usage-cost
openclaw gateway usage-cost --days 7
openclaw gateway usage-cost --json
```
الخيارات:
- `--days <days>`: عدد الأيام المطلوب تضمينها (الافتراضي `30`).
### `gateway status`
يعرض `gateway status` خدمة Gateway ‏(launchd/systemd/schtasks) بالإضافة إلى فحص RPC اختياري.
```bash
openclaw gateway status
openclaw gateway status --json
openclaw gateway status --require-rpc
```
الخيارات:
- `--url <url>`: إضافة هدف فحص صريح. لا يزال يتم فحص configured remote + localhost.
- `--token <token>`: مصادقة token للفحص.
- `--password <password>`: مصادقة كلمة المرور للفحص.
- `--timeout <ms>`: مهلة الفحص (الافتراضي `10000`).
- `--no-probe`: تخطي فحص RPC (عرض الخدمة فقط).
- `--deep`: فحص خدمات على مستوى النظام أيضًا.
- `--require-rpc`: الخروج بقيمة غير صفرية عندما يفشل فحص RPC. لا يمكن دمجه مع `--no-probe`.
ملاحظات:
- يظل `gateway status` متاحًا للتشخيص حتى عندما تكون تهيئة CLI المحلية مفقودة أو غير صالحة.
- يقوم `gateway status` بحل SecretRefs الخاصة بالمصادقة المهيأة لمصادقة الفحص عند الإمكان.
- إذا كان SecretRef مطلوبًا للمصادقة وغير محلول في مسار هذا الأمر، فإن `gateway status --json` يبلّغ عن `rpc.authWarning` عندما يفشل اتصال/مصادقة probe؛ مرّر `--token`/`--password` صراحة أو أصلح مصدر السر أولًا.
- إذا نجح الفحص، يتم كتم تحذيرات auth-ref غير المحلولة لتجنب الإيجابيات الكاذبة.
- استخدم `--require-rpc` في البرامج النصية والأتمتة عندما لا يكفي وجود خدمة تستمع وتحتاج إلى أن تكون Gateway RPC نفسها سليمة.
- يضيف `--deep` فحصًا بأفضل جهد لعمليات تثبيت إضافية في launchd/systemd/schtasks. وعند اكتشاف عدة خدمات شبيهة بـ gateway، يطبع الإخراج البشري تلميحات للتنظيف ويحذر من أن معظم الإعدادات يجب أن تشغّل gateway واحدًا لكل جهاز.
- يتضمن الإخراج البشري مسار سجل الملف المحلول بالإضافة إلى لقطة من مسارات/صلاحية التهيئة بين CLI والخدمة للمساعدة في تشخيص انجراف profile أو state-dir.
- في عمليات تثبيت Linux systemd، تقرأ فحوصات انجراف مصادقة الخدمة قيم `Environment=` و`EnvironmentFile=` من الوحدة (بما في ذلك `%h` والمسارات المقتبسة والملفات المتعددة وملفات `-` الاختيارية).
- تحل فحوصات الانجراف `gateway.auth.token` SecretRefs باستخدام merged runtime env ‏(بيئة أمر الخدمة أولًا، ثم process env كاحتياطي).
- إذا لم تكن مصادقة token مفعّلة فعليًا (وضع `gateway.auth.mode` صريح بقيمة `password`/`none`/`trusted-proxy`، أو وضع غير مضبوط حيث يمكن أن تفوز كلمة المرور ولا يوجد مرشح token يمكنه الفوز)، فإن فحوصات انجراف token تتخطى حل token من التهيئة.
### `gateway probe`
الأمر `gateway probe` هو أمر "تصحيح كل شيء". وهو يفحص دائمًا:
- الـ remote gateway المهيأ لديك (إن وُجد)، و
- localhost ‏(loopback) **حتى إذا كان remote مهيأ**.
إذا مرّرت `--url`، يُضاف هذا الهدف الصريح قبلهما معًا. ويُسمّي الإخراج البشري
الأهداف كما يلي:
- `URL (explicit)`
- `Remote (configured)` أو `Remote (configured, inactive)`
- `Local loopback`
إذا أمكن الوصول إلى عدة Gateways، فسيطبعها جميعًا. وتُدعَم عدة Gateways عند استخدام profiles/mنافذ معزولة (مثل rescue bot)، لكن معظم عمليات التثبيت ما زالت تشغّل gateway واحدًا.
```bash
openclaw gateway probe
openclaw gateway probe --json
```
التفسير:
- `Reachable: yes` تعني أن هدفًا واحدًا على الأقل قبل اتصال WebSocket.
- `RPC: ok` تعني أن استدعاءات RPC التفصيلية (`health`/`status`/`system-presence`/`config.get`) نجحت أيضًا.
- `RPC: limited - missing scope: operator.read` تعني أن الاتصال نجح لكن RPC التفصيلي كان محدود النطاق. ويتم الإبلاغ عن هذا على أنه وصول **متدهور**، وليس فشلًا كاملًا.
- تكون قيمة الخروج غير صفرية فقط عندما لا يكون أي هدف تم فحصه قابلًا للوصول.
ملاحظات JSON ‏(`--json`):
- المستوى الأعلى:
- `ok`: يمكن الوصول إلى هدف واحد على الأقل.
- `degraded`: كان لدى هدف واحد على الأقل RPC تفصيلي محدود النطاق.
- `primaryTargetId`: أفضل هدف يُعامل على أنه الفائز النشط بهذا الترتيب: URL صريح، نفق SSH، configured remote، ثم Local loopback.
- `warnings[]`: سجلات تحذير بأفضل جهد تحتوي على `code` و`message` و`targetIds` الاختيارية.
- `network`: تلميحات URL لـ Local loopback/tailnet مشتقة من التهيئة الحالية وشبكات المضيف.
- `discovery.timeoutMs` و`discovery.count`: ميزانية/عدد نتائج الاكتشاف الفعليان المستخدمان في تمريرة الفحص هذه.
- لكل هدف (`targets[].connect`):
- `ok`: إمكانية الوصول بعد الاتصال + تصنيف التدهور.
- `rpcOk`: نجاح RPC التفصيلي الكامل.
- `scopeLimited`: فشل RPC التفصيلي بسبب غياب نطاق operator.
رموز التحذير الشائعة:
- `ssh_tunnel_failed`: فشل إعداد نفق SSH؛ وعاد الأمر إلى الفحوصات المباشرة.
- `multiple_gateways`: أمكن الوصول إلى أكثر من هدف واحد؛ وهذا غير معتاد إلا إذا كنت تشغّل عمدًا profiles معزولة، مثل rescue bot.
- `auth_secretref_unresolved`: تعذر حل SecretRef مصادقة مهيأ لهدف فاشل.
- `probe_scope_limited`: نجح اتصال WebSocket، لكن RPC التفصيلي كان محدودًا بسبب غياب `operator.read`.
#### Remote عبر SSH ‏(مماثل لتطبيق Mac)
يستخدم وضع "Remote over SSH" في تطبيق macOS إعادة توجيه منفذ محلية بحيث يصبح الـ remote gateway (الذي قد يكون مرتبطًا بـ loopback فقط) قابلاً للوصول على `ws://127.0.0.1:<port>`.
المكافئ في CLI:
```bash
openclaw gateway probe --ssh user@gateway-host
```
الخيارات:
- `--ssh <target>`: ‏`user@host` أو `user@host:port` (يكون المنفذ افتراضيًا `22`).
- `--ssh-identity <path>`: ملف الهوية.
- `--ssh-auto`: اختيار أول مضيف gateway مكتشف كهدف SSH من نقطة نهاية
الاكتشاف المحلولة (`local.` بالإضافة إلى wide-area domain المهيأ، إن وجد). ويتم تجاهل
التلميحات المعتمدة على TXT فقط.
التهيئة (اختيارية، وتُستخدم كقيم افتراضية):
- `gateway.remote.sshTarget`
- `gateway.remote.sshIdentity`
### `gateway call <method>`
مساعد RPC منخفض المستوى.
```bash
openclaw gateway call status
openclaw gateway call logs.tail --params '{"sinceMs": 60000}'
```
الخيارات:
- `--params <json>`: سلسلة كائن JSON للمعلمات (الافتراضي `{}`)
- `--url <url>`
- `--token <token>`
- `--password <password>`
- `--timeout <ms>`
- `--expect-final`
- `--json`
ملاحظات:
- يجب أن تكون `--params` قيمة JSON صالحة.
- يُستخدم `--expect-final` بشكل أساسي مع RPCs على نمط الوكيل التي تبث أحداثًا وسيطة قبل payload نهائي.
## إدارة خدمة Gateway
```bash
openclaw gateway install
openclaw gateway start
openclaw gateway stop
openclaw gateway restart
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 uninstall|start|stop|restart`: ‏`--json`
ملاحظات:
- يدعم `gateway install` الخيارات `--port` و`--runtime` و`--token` و`--force` و`--json`.
- عندما تتطلب مصادقة token وجود token وكان `gateway.auth.token` مُدارًا عبر SecretRef، فإن `gateway install` يتحقق من أن SecretRef قابل للحل لكنه لا يخزن token المحلول في بيانات تعريف بيئة الخدمة.
- إذا كانت مصادقة token تتطلب token وكان SecretRef الخاص بالـ token المهيأ غير محلول، فإن التثبيت يفشل بشكل مغلق بدلًا من حفظ نص صريح احتياطي.
- بالنسبة إلى مصادقة كلمة المرور في `gateway run`، ففضّل `OPENCLAW_GATEWAY_PASSWORD` أو `--password-file` أو `gateway.auth.password` المدعوم بـ SecretRef بدلًا من `--password` المضمن.
- في وضع المصادقة المستنتج، لا يخفف `OPENCLAW_GATEWAY_PASSWORD` الموجود في shell فقط متطلبات token الخاصة بالتثبيت؛ استخدم تهيئة دائمة (`gateway.auth.password` أو config `env`) عند تثبيت خدمة مُدارة.
- إذا كان كل من `gateway.auth.token` و`gateway.auth.password` مهيأين وكانت `gateway.auth.mode` غير مضبوطة، فسيتم حظر التثبيت حتى يُضبط الوضع صراحة.
- تقبل أوامر دورة الحياة `--json` للاستخدام في البرامج النصية.
## اكتشاف Gateways ‏(Bonjour)
يقوم `gateway discover` بفحص beacons الخاصة بـ Gateway ‏(`_openclaw-gw._tcp`).
- Multicast DNS-SD: ‏`local.`
- Unicast DNS-SD ‏(Wide-Area Bonjour): اختر domain (مثال: `openclaw.internal.`) وأعد إعداد split DNS + خادم DNS؛ راجع [/gateway/bonjour](/gateway/bonjour)
تعلن فقط الـ Gateways التي يكون فيها اكتشاف Bonjour مفعّلًا (افتراضيًا) عن الـ beacon.
تتضمن سجلات الاكتشاف Wide-Area ‏(TXT):
- `role` (تلميح دور gateway)
- `transport` (تلميح النقل، مثل `gateway`)
- `gatewayPort` (منفذ WebSocket، وعادةً `18789`)
- `sshPort` (اختياري؛ تستخدم العملاء افتراضيًا أهداف SSH على `22` عند غيابه)
- `tailnetDns` (اسم مضيف MagicDNS، عند توفره)
- `gatewayTls` / `gatewayTlsSha256` (تمكين TLS + بصمة الشهادة)
- `cliPath` (تلميح تثبيت remote مكتوب إلى wide-area zone)
### `gateway discover`
```bash
openclaw gateway discover
```
الخيارات:
- `--timeout <ms>`: المهلة لكل أمر (browse/resolve)؛ الافتراضي `2000`.
- `--json`: إخراج قابل للقراءة آليًا (ويعطل أيضًا التنسيق/مؤشر الدوران).
أمثلة:
```bash
openclaw gateway discover --timeout 4000
openclaw gateway discover --json | jq '.beacons[].wsUrl'
```
ملاحظات:
- يفحص CLI كلاً من `local.` وwide-area domain المهيأ عندما يكون أحدها مفعّلًا.
- يتم اشتقاق `wsUrl` في إخراج JSON من نقطة نهاية الخدمة المحلولة، وليس من
التلميحات المعتمدة على TXT فقط مثل `lanHost` أو `tailnetDns`.
- في mDNS الخاص بـ `local.`، لا يتم بث `sshPort` و`cliPath` إلا عندما
تكون `discovery.mdns.mode` هي `full`. أما Wide-area DNS-SD فلا يزال يكتب `cliPath`؛
ويبقى `sshPort` اختياريًا هناك أيضًا.

43
docs/ar/cli/health.md Normal file
View File

@ -0,0 +1,43 @@
---
read_when:
- أنت تريد التحقق سريعًا من صحة البوابة قيد التشغيل
summary: مرجع CLI للأمر `openclaw health` (لقطة لصحة البوابة عبر RPC)
title: health
x-i18n:
generated_at: "2026-04-05T12:38:19Z"
model: gpt-5.4
provider: openai
source_hash: 4ed2b9ceefee6159cabaae9172d2d88174626456e7503d5d2bcd142634188ff0
source_path: cli/health.md
workflow: 15
---
# `openclaw health`
اجلب معلومات الصحة من البوابة قيد التشغيل.
الخيارات:
- `--json`: مخرجات قابلة للقراءة آليًا
- `--timeout <ms>`: مهلة الاتصال بالمللي ثانية (الافتراضي `10000`)
- `--verbose`: تسجيل مفصل
- `--debug`: اسم بديل لـ `--verbose`
أمثلة:
```bash
openclaw health
openclaw health --json
openclaw health --timeout 2500
openclaw health --verbose
openclaw health --debug
```
ملاحظات:
- يطلب `openclaw health` الافتراضي لقطة الصحة من البوابة قيد التشغيل. عندما
تكون لدى البوابة بالفعل لقطة مخزنة مؤقتًا وحديثة، يمكنها إرجاع تلك الحمولة المخزنة مؤقتًا
والتحديث في الخلفية.
- يفرض `--verbose` إجراء فحص مباشر، ويطبع تفاصيل اتصال البوابة، ويوسّع
المخرجات المقروءة للبشر لتشمل جميع الحسابات والوكلاء المهيئين.
- تتضمن المخرجات مخازن جلسات لكل وكيل عند تهيئة عدة وكلاء.

344
docs/ar/cli/hooks.md Normal file
View File

@ -0,0 +1,344 @@
---
read_when:
- أنت تريد إدارة خطافات الوكيل
- أنت تريد فحص توفر الخطافات أو تفعيل خطافات مساحة العمل
summary: مرجع CLI للأمر `openclaw hooks` (خطافات الوكيل)
title: hooks
x-i18n:
generated_at: "2026-04-05T12:38:40Z"
model: gpt-5.4
provider: openai
source_hash: 8dc9144e9844e9c3cdef2514098eb170543746fcc55ca5a1cc746c12d80209e7
source_path: cli/hooks.md
workflow: 15
---
# `openclaw hooks`
إدارة خطافات الوكيل (عمليات أتمتة مدفوعة بالأحداث لأوامر مثل `/new` و`/reset` وبدء تشغيل البوابة).
يُعادل تشغيل `openclaw hooks` من دون أمر فرعي تشغيل `openclaw hooks list`.
ذو صلة:
- الخطافات: [Hooks](/automation/hooks)
- خطافات plugin: [خطافات Plugin](/plugins/architecture#provider-runtime-hooks)
## سرد جميع الخطافات
```bash
openclaw hooks list
```
يسرد جميع الخطافات المكتشفة من أدلة مساحة العمل، والمدارة، والإضافية، والمضمنة.
**الخيارات:**
- `--eligible`: عرض الخطافات المؤهلة فقط (التي استوفت المتطلبات)
- `--json`: إخراج بصيغة JSON
- `-v, --verbose`: عرض معلومات تفصيلية بما في ذلك المتطلبات المفقودة
**مثال على الإخراج:**
```
Hooks (4/4 ready)
Ready:
🚀 boot-md ✓ - Run BOOT.md on gateway startup
📎 bootstrap-extra-files ✓ - Inject extra workspace bootstrap files during agent bootstrap
📝 command-logger ✓ - Log all command events to a centralized audit file
💾 session-memory ✓ - Save session context to memory when /new or /reset command is issued
```
**مثال (verbose):**
```bash
openclaw hooks list --verbose
```
يعرض المتطلبات المفقودة للخطافات غير المؤهلة.
**مثال (JSON):**
```bash
openclaw hooks list --json
```
يعيد JSON منظمًا للاستخدام البرمجي.
## الحصول على معلومات الخطاف
```bash
openclaw hooks info <name>
```
يعرض معلومات تفصيلية عن خطاف محدد.
**الوسائط:**
- `<name>`: اسم الخطاف أو مفتاح الخطاف (مثل `session-memory`)
**الخيارات:**
- `--json`: إخراج بصيغة JSON
**مثال:**
```bash
openclaw hooks info session-memory
```
**الإخراج:**
```
💾 session-memory ✓ Ready
Save session context to memory when /new or /reset command is issued
Details:
Source: openclaw-bundled
Path: /path/to/openclaw/hooks/bundled/session-memory/HOOK.md
Handler: /path/to/openclaw/hooks/bundled/session-memory/handler.ts
Homepage: https://docs.openclaw.ai/automation/hooks#session-memory
Events: command:new, command:reset
Requirements:
Config: ✓ workspace.dir
```
## التحقق من أهلية الخطافات
```bash
openclaw hooks check
```
يعرض ملخصًا لحالة أهلية الخطافات (عدد الخطافات الجاهزة مقابل غير الجاهزة).
**الخيارات:**
- `--json`: إخراج بصيغة JSON
**مثال على الإخراج:**
```
Hooks Status
Total hooks: 4
Ready: 4
Not ready: 0
```
## تفعيل خطاف
```bash
openclaw hooks enable <name>
```
يفعّل خطافًا محددًا بإضافته إلى إعداداتك (`~/.openclaw/openclaw.json` افتراضيًا).
**ملاحظة:** تكون خطافات مساحة العمل معطلة افتراضيًا حتى يتم تفعيلها هنا أو في الإعدادات. وتظهر الخطافات التي تديرها plugins على شكل `plugin:<id>` في `openclaw hooks list` ولا يمكن تفعيلها/تعطيلها هنا. قم بتفعيل/تعطيل plugin نفسه بدلًا من ذلك.
**الوسائط:**
- `<name>`: اسم الخطاف (مثل `session-memory`)
**مثال:**
```bash
openclaw hooks enable session-memory
```
**الإخراج:**
```
✓ Enabled hook: 💾 session-memory
```
**ما الذي يفعله:**
- يتحقق من وجود الخطاف وأنه مؤهل
- يحدّث `hooks.internal.entries.<name>.enabled = true` في إعداداتك
- يحفظ الإعدادات على القرص
إذا كان الخطاف قد جاء من `<workspace>/hooks/`، فإن خطوة الاشتراك هذه مطلوبة قبل
أن تقوم البوابة بتحميله.
**بعد التفعيل:**
- أعد تشغيل البوابة حتى تعيد الخطافات التحميل (إعادة تشغيل تطبيق شريط القوائم على macOS، أو أعد تشغيل عملية البوابة في وضع التطوير).
## تعطيل خطاف
```bash
openclaw hooks disable <name>
```
يعطّل خطافًا محددًا عبر تحديث إعداداتك.
**الوسائط:**
- `<name>`: اسم الخطاف (مثل `command-logger`)
**مثال:**
```bash
openclaw hooks disable command-logger
```
**الإخراج:**
```
⏸ Disabled hook: 📝 command-logger
```
**بعد التعطيل:**
- أعد تشغيل البوابة حتى تعيد الخطافات التحميل
## ملاحظات
- تكتب الأوامر `openclaw hooks list --json` و`info --json` و`check --json` JSON منظمًا مباشرة إلى stdout.
- لا يمكن تفعيل أو تعطيل الخطافات التي تديرها plugins هنا؛ قم بتفعيل أو تعطيل plugin المالك بدلًا من ذلك.
## تثبيت حزم الخطافات
```bash
openclaw plugins install <package> # ClawHub أولًا، ثم npm
openclaw plugins install <package> --pin # تثبيت الإصدار
openclaw plugins install <path> # مسار محلي
```
ثبّت حزم الخطافات من خلال مثبّت plugins الموحد.
لا يزال `openclaw hooks install` يعمل كاسم مستعار للتوافق، لكنه يطبع
تحذير إهمال ويعيد التوجيه إلى `openclaw plugins install`.
تكون مواصفات npm **خاصة بالسجل فقط** (اسم الحزمة + **إصدار دقيق** اختياري أو
**dist-tag**). ويتم رفض مواصفات Git/URL/file ونطاقات semver. وتُشغَّل
عمليات تثبيت التبعيات باستخدام `--ignore-scripts` لأسباب تتعلق بالأمان.
تبقى المواصفات المجردة و`@latest` على المسار المستقر. وإذا قام npm بحل أيٍّ من
هذين إلى إصدار prerelease، فسيتوقف OpenClaw ويطلب منك الاشتراك صراحةً باستخدام
وسم prerelease مثل `@beta`/`@rc` أو إصدار prerelease دقيق.
**ما الذي يفعله:**
- ينسخ حزمة الخطافات إلى `~/.openclaw/hooks/<id>`
- يفعّل الخطافات المثبتة في `hooks.internal.entries.*`
- يسجل التثبيت ضمن `hooks.internal.installs`
**الخيارات:**
- `-l, --link`: ربط دليل محلي بدلًا من نسخه (يضيفه إلى `hooks.internal.load.extraDirs`)
- `--pin`: تسجيل عمليات تثبيت npm على شكل `name@version` محلول ودقيق في `hooks.internal.installs`
**الأرشيفات المدعومة:** `.zip`, `.tgz`, `.tar.gz`, `.tar`
**أمثلة:**
```bash
# دليل محلي
openclaw plugins install ./my-hook-pack
# أرشيف محلي
openclaw plugins install ./my-hook-pack.zip
# حزمة NPM
openclaw plugins install @openclaw/my-hook-pack
# ربط دليل محلي من دون نسخه
openclaw plugins install -l ./my-hook-pack
```
تُعامل حزم الخطافات المرتبطة على أنها خطافات مُدارة من دليل
مُعد من المشغّل، وليست خطافات مساحة عمل.
## تحديث حزم الخطافات
```bash
openclaw plugins update <id>
openclaw plugins update --all
```
حدّث حزم الخطافات المعتمدة على npm والمتعقبة من خلال محدّث plugins الموحد.
لا يزال `openclaw hooks update` يعمل كاسم مستعار للتوافق، لكنه يطبع
تحذير إهمال ويعيد التوجيه إلى `openclaw plugins update`.
**الخيارات:**
- `--all`: تحديث جميع حزم الخطافات المتعقبة
- `--dry-run`: عرض ما سيتغير من دون كتابة
عند وجود قيمة hash سلامة مخزنة وتغيّر hash الأثر الذي تم جلبه،
يطبع OpenClaw تحذيرًا ويطلب التأكيد قبل المتابعة. استخدم
القيمة العامة `--yes` لتجاوز المطالبات في تشغيلات CI/غير التفاعلية.
## الخطافات المضمنة
### session-memory
يحفظ سياق الجلسة في الذاكرة عند إصدار `/new` أو `/reset`.
**التفعيل:**
```bash
openclaw hooks enable session-memory
```
**الإخراج:** `~/.openclaw/workspace/memory/YYYY-MM-DD-slug.md`
**راجع:** [توثيق session-memory](/automation/hooks#session-memory)
### bootstrap-extra-files
يحقن ملفات bootstrap إضافية (على سبيل المثال `AGENTS.md` / `TOOLS.md` محلية في monorepo) أثناء `agent:bootstrap`.
**التفعيل:**
```bash
openclaw hooks enable bootstrap-extra-files
```
**راجع:** [توثيق bootstrap-extra-files](/automation/hooks#bootstrap-extra-files)
### command-logger
يسجل جميع أحداث الأوامر في ملف تدقيق مركزي.
**التفعيل:**
```bash
openclaw hooks enable command-logger
```
**الإخراج:** `~/.openclaw/logs/commands.log`
**عرض السجلات:**
```bash
# الأوامر الحديثة
tail -n 20 ~/.openclaw/logs/commands.log
# تنسيق جميل
cat ~/.openclaw/logs/commands.log | jq .
# التصفية حسب الإجراء
grep '"action":"new"' ~/.openclaw/logs/commands.log | jq .
```
**راجع:** [توثيق command-logger](/automation/hooks#command-logger)
### boot-md
يشغّل `BOOT.md` عند بدء البوابة (بعد بدء القنوات).
**الأحداث**: `gateway:startup`
**التفعيل**:
```bash
openclaw hooks enable boot-md
```
**راجع:** [توثيق boot-md](/automation/hooks#boot-md)

1843
docs/ar/cli/index.md Normal file
View File

File diff suppressed because it is too large Load Diff

66
docs/ar/cli/logs.md Normal file
View File

@ -0,0 +1,66 @@
---
read_when:
- تحتاج إلى تتبّع سجلات Gateway عن بُعد (من دون SSH)
- تريد أسطر سجلات JSON لأغراض الأدوات
summary: مرجع CLI للأمر `openclaw logs` (تتبّع سجلات gateway عبر RPC)
title: logs
x-i18n:
generated_at: "2026-04-05T12:38:28Z"
model: gpt-5.4
provider: openai
source_hash: 238a52e31a9a332cab513ced049e92d032b03c50376895ce57dffa2ee7d1e4b4
source_path: cli/logs.md
workflow: 15
---
# `openclaw logs`
تتبّع سجلات ملفات Gateway عبر RPC ‏(يعمل في الوضع البعيد).
ذو صلة:
- نظرة عامة على التسجيل: [التسجيل](/logging)
- CLI الخاص بـ Gateway: [gateway](/cli/gateway)
## الخيارات
- `--limit <n>`: الحد الأقصى لعدد أسطر السجل المطلوب إرجاعها (الافتراضي `200`)
- `--max-bytes <n>`: الحد الأقصى للبايتات المقروءة من ملف السجل (الافتراضي `250000`)
- `--follow`: متابعة تدفق السجل
- `--interval <ms>`: فترة الاستطلاع أثناء المتابعة (الافتراضي `1000`)
- `--json`: إخراج أحداث JSON مفصولة بأسطر
- `--plain`: إخراج نص عادي من دون تنسيق مزيّن
- `--no-color`: تعطيل ألوان ANSI
- `--local-time`: عرض الطوابع الزمنية في منطقتك الزمنية المحلية
## خيارات Gateway RPC المشتركة
يقبل `openclaw logs` أيضًا علامات عميل Gateway القياسية:
- `--url <url>`: عنوان Gateway WebSocket URL
- `--token <token>`: رمز Gateway
- `--timeout <ms>`: المهلة بالمللي ثانية (الافتراضي `30000`)
- `--expect-final`: الانتظار حتى الاستجابة النهائية عندما يكون استدعاء Gateway مدعومًا من وكيل
عند تمرير `--url`، لا يطبّق CLI تلقائيًا بيانات الاعتماد من الإعداد أو البيئة. أدرج `--token` صراحةً إذا كان Gateway الهدف يتطلب المصادقة.
## أمثلة
```bash
openclaw logs
openclaw logs --follow
openclaw logs --follow --interval 2000
openclaw logs --limit 500 --max-bytes 500000
openclaw logs --json
openclaw logs --plain
openclaw logs --no-color
openclaw logs --limit 500
openclaw logs --local-time
openclaw logs --follow --local-time
openclaw logs --url ws://127.0.0.1:18789 --token "$OPENCLAW_GATEWAY_TOKEN"
```
## ملاحظات
- استخدم `--local-time` لعرض الطوابع الزمنية في منطقتك الزمنية المحلية.
- إذا طلب Gateway على local loopback المحلي إقرانًا، يعود `openclaw logs` تلقائيًا إلى ملف السجل المحلي المُكوَّن. ولا تستخدم أهداف `--url` الصريحة هذا السلوك الاحتياطي.

512
docs/ar/cli/mcp.md Normal file
View File

@ -0,0 +1,512 @@
---
read_when:
- ربط Codex أو Claude Code أو عميل MCP آخر بقنوات مدعومة من OpenClaw
- تشغيل `openclaw mcp serve`
- إدارة تعريفات خوادم MCP المحفوظة في OpenClaw
summary: كشف محادثات قنوات OpenClaw عبر MCP وإدارة تعريفات خوادم MCP المحفوظة في OpenClaw
title: mcp
x-i18n:
generated_at: "2026-04-05T12:39:20Z"
model: gpt-5.4
provider: openai
source_hash: b35de9e14f96666eeca2f93c06cb214e691152f911d45ee778efe9cf5bf96cc2
source_path: cli/mcp.md
workflow: 15
---
# mcp
لدى `openclaw mcp` مهمتان:
- تشغيل OpenClaw كخادم MCP باستخدام `openclaw mcp serve`
- إدارة تعريفات خوادم MCP الصادرة والمملوكة لـ OpenClaw باستخدام `list` و`show`،
و`set`، و`unset`
بمعنى آخر:
- `serve` يعني أن OpenClaw يعمل كخادم MCP
- `list` / `show` / `set` / `unset` تعني أن OpenClaw يعمل كسجل
MCP من جهة العميل لخوادم MCP أخرى قد تستهلكها بيئات تشغيله لاحقًا
استخدم [`openclaw acp`](/cli/acp) عندما يجب أن يستضيف OpenClaw
جلسة حزمة ترميز بنفسه ويوجه وقت التشغيل هذا عبر ACP.
## OpenClaw كخادم MCP
هذا هو مسار `openclaw mcp serve`.
## متى تستخدم `serve`
استخدم `openclaw mcp serve` عندما:
- يجب أن يتحدث Codex أو Claude Code أو عميل MCP آخر مباشرةً إلى
محادثات القنوات المدعومة من OpenClaw
- يكون لديك بالفعل Gateway محلي أو بعيد لـ OpenClaw مع جلسات موجهة
- تريد خادم MCP واحدًا يعمل عبر واجهات القنوات في OpenClaw بدلًا
من تشغيل جسور منفصلة لكل قناة
استخدم [`openclaw acp`](/cli/acp) بدلًا من ذلك عندما يجب على OpenClaw استضافة
وقت تشغيل الترميز نفسه والإبقاء على جلسة الوكيل داخل OpenClaw.
## كيف يعمل
يبدأ `openclaw mcp serve` خادم MCP عبر stdio. يمتلك عميل MCP
هذه العملية. وبينما يُبقي العميل جلسة stdio مفتوحة، يتصل الجسر بـ
OpenClaw Gateway محلي أو بعيد عبر WebSocket ويكشف محادثات القنوات
الموجّهة عبر MCP.
دورة الحياة:
1. يشغّل عميل MCP الأمر `openclaw mcp serve`
2. يتصل الجسر بـ Gateway
3. تصبح الجلسات الموجّهة محادثات MCP وأدوات النصوص/السجل
4. تُصفّ أحداث البث المباشر في الذاكرة بينما يكون الجسر متصلًا
5. إذا كان وضع قناة Claude مفعّلًا، يمكن للجلسة نفسها أيضًا تلقي
إشعارات دفع خاصة بـ Claude
سلوك مهم:
- تبدأ حالة قائمة الانتظار الحية عندما يتصل الجسر
- يُقرأ سجل النصوص الأقدم باستخدام `messages_read`
- لا توجد إشعارات دفع Claude إلا أثناء بقاء جلسة MCP حيّة
- عندما ينفصل العميل، يخرج الجسر وتختفي قائمة الانتظار الحية
## اختر وضع العميل
استخدم الجسر نفسه بطريقتين مختلفتين:
- عملاء MCP العامون: أدوات MCP قياسية فقط. استخدم `conversations_list`،
و`messages_read`، و`events_poll`، و`events_wait`، و`messages_send`، و
أدوات الموافقة.
- Claude Code: أدوات MCP القياسية بالإضافة إلى مكيّف القناة الخاص بـ Claude.
فعّل `--claude-channel-mode on` أو اترك القيمة الافتراضية `auto`.
حاليًا، يتصرف `auto` بالطريقة نفسها التي يتصرف بها `on`. لا يوجد اكتشاف
لقدرات العميل بعد.
## ما الذي يكشفه `serve`
يستخدم الجسر بيانات تعريف مسار الجلسة الموجودة في Gateway لكشف
المحادثات المدعومة بالقنوات. تظهر المحادثة عندما يكون لدى OpenClaw بالفعل
حالة جلسة مع مسار معروف مثل:
- `channel`
- بيانات تعريف المستلم أو الوجهة
- `accountId` اختياري
- `threadId` اختياري
وهذا يمنح عملاء MCP مكانًا واحدًا من أجل:
- إدراج المحادثات الموجهة الحديثة
- قراءة سجل النصوص الحديث
- انتظار أحداث واردة جديدة
- إرسال رد عبر المسار نفسه
- رؤية طلبات الموافقة التي تصل بينما يكون الجسر متصلًا
## الاستخدام
```bash
# Gateway محلي
openclaw mcp serve
# Gateway بعيد
openclaw mcp serve --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token
# Gateway بعيد مع مصادقة كلمة مرور
openclaw mcp serve --url wss://gateway-host:18789 --password-file ~/.openclaw/gateway.password
# تمكين سجلات الجسر المفصلة
openclaw mcp serve --verbose
# تعطيل إشعارات الدفع الخاصة بـ Claude
openclaw mcp serve --claude-channel-mode off
```
## أدوات الجسر
يكشف الجسر الحالي أدوات MCP التالية:
- `conversations_list`
- `conversation_get`
- `messages_read`
- `attachments_fetch`
- `events_poll`
- `events_wait`
- `messages_send`
- `permissions_list_open`
- `permissions_respond`
### `conversations_list`
يسرد المحادثات الحديثة المدعومة بالجلسات والتي لديها بالفعل بيانات تعريف
المسار في حالة جلسة Gateway.
مرشحات مفيدة:
- `limit`
- `search`
- `channel`
- `includeDerivedTitles`
- `includeLastMessage`
### `conversation_get`
يعيد محادثة واحدة حسب `session_key`.
### `messages_read`
يقرأ رسائل النصوص الحديثة لمحادثة واحدة مدعومة بالجلسة.
### `attachments_fetch`
يستخرج كتل محتوى الرسائل غير النصية من رسالة نصية واحدة. هذه
رؤية للبيانات الوصفية فوق محتوى النصوص، وليست مخزن كتل مرفقات
دائمًا مستقلًا.
### `events_poll`
يقرأ الأحداث الحية الموجودة في قائمة الانتظار بدءًا من مؤشر رقمي.
### `events_wait`
يجري long-poll حتى يصل الحدث المطابق التالي الموجود في قائمة الانتظار أو
تنتهي المهلة.
استخدم هذا عندما يحتاج عميل MCP عام إلى تسليم شبه فوري دون
بروتوكول دفع خاص بـ Claude.
### `messages_send`
يرسل نصًا مرة أخرى عبر المسار نفسه المسجل بالفعل على الجلسة.
السلوك الحالي:
- يتطلب مسار محادثة موجودًا
- يستخدم القناة الخاصة بالجلسة، والمستلم، ومعرّف الحساب، ومعرّف السلسلة
- يرسل نصًا فقط
### `permissions_list_open`
يسرد طلبات موافقة exec/plugin المعلقة التي لاحظها الجسر منذ
اتصاله بـ Gateway.
### `permissions_respond`
يعالج طلب موافقة exec/plugin معلقًا واحدًا باستخدام:
- `allow-once`
- `allow-always`
- `deny`
## نموذج الأحداث
يحتفظ الجسر بقائمة انتظار أحداث داخل الذاكرة أثناء اتصاله.
أنواع الأحداث الحالية:
- `message`
- `exec_approval_requested`
- `exec_approval_resolved`
- `plugin_approval_requested`
- `plugin_approval_resolved`
- `claude_permission_request`
قيود مهمة:
- قائمة الانتظار حية فقط؛ تبدأ عندما يبدأ جسر MCP
- لا يعيد `events_poll` و`events_wait` تشغيل سجل Gateway الأقدم
من تلقاء نفسيهما
- يجب قراءة التراكم الدائم باستخدام `messages_read`
## إشعارات قناة Claude
يمكن للجسر أيضًا كشف إشعارات قنوات خاصة بـ Claude. وهذا هو
المكافئ في OpenClaw لمكيّف قناة Claude Code: تظل أدوات MCP القياسية متاحة،
لكن الرسائل الواردة الحية يمكن أن تصل أيضًا كإشعارات MCP خاصة بـ Claude.
العلامات:
- `--claude-channel-mode off`: أدوات MCP قياسية فقط
- `--claude-channel-mode on`: تمكين إشعارات قناة Claude
- `--claude-channel-mode auto`: القيمة الافتراضية الحالية؛ سلوك الجسر نفسه كما في `on`
عند تمكين وضع قناة Claude، يعلن الخادم عن قدرات Claude التجريبية
ويمكنه إصدار:
- `notifications/claude/channel`
- `notifications/claude/channel/permission`
السلوك الحالي للجسر:
- تُعاد توجيه رسائل النصوص الواردة من نوع `user` كـ
`notifications/claude/channel`
- تُتتبع طلبات أذونات Claude المستلمة عبر MCP داخل الذاكرة
- إذا أرسلت المحادثة المرتبطة لاحقًا `yes abcde` أو `no abcde`، فإن الجسر
يحوّل ذلك إلى `notifications/claude/channel/permission`
- هذه الإشعارات مخصصة للجلسة الحية فقط؛ إذا انفصل عميل MCP،
فلا يوجد هدف دفع
هذا مقصود ليكون خاصًا بالعميل. يجب على عملاء MCP العامين الاعتماد على
أدوات الاستطلاع القياسية.
## إعداد عميل MCP
مثال على إعداد عميل stdio:
```json
{
"mcpServers": {
"openclaw": {
"command": "openclaw",
"args": [
"mcp",
"serve",
"--url",
"wss://gateway-host:18789",
"--token-file",
"/path/to/gateway.token"
]
}
}
}
```
بالنسبة إلى معظم عملاء MCP العامين، ابدأ بسطح الأدوات القياسي وتجاهل
وضع Claude. فعّل وضع Claude فقط للعملاء الذين يفهمون فعليًا
طرق الإشعارات الخاصة بـ Claude.
## الخيارات
يدعم `openclaw mcp serve` ما يلي:
- `--url <url>`: عنوان URL لـ Gateway WebSocket
- `--token <token>`: رمز Gateway المميز
- `--token-file <path>`: قراءة الرمز المميز من ملف
- `--password <password>`: كلمة مرور Gateway
- `--password-file <path>`: قراءة كلمة المرور من ملف
- `--claude-channel-mode <auto|on|off>`: وضع إشعارات Claude
- `-v`, `--verbose`: سجلات مفصلة على stderr
فضّل `--token-file` أو `--password-file` بدلًا من الأسرار المضمنة متى أمكن.
## الأمان وحدود الثقة
لا يخترع الجسر التوجيه. بل يكشف فقط المحادثات التي يعرف Gateway
بالفعل كيفية توجيهها.
وهذا يعني:
- تظل قوائم سماح المرسلين، والاقتران، والثقة على مستوى القناة تابعة لـ
إعدادات قناة OpenClaw الأساسية
- يمكن لـ `messages_send` الرد فقط عبر مسار مخزن موجود
- تكون حالة الموافقة حية/في الذاكرة فقط لجلسة الجسر الحالية
- يجب أن تستخدم مصادقة الجسر عناصر تحكم الرمز المميز أو كلمة المرور في Gateway نفسها
التي ستثق بها لأي عميل Gateway بعيد آخر
إذا كانت محادثة مفقودة من `conversations_list`، فالسبب المعتاد ليس
إعداد MCP. بل هو فقدان بيانات تعريف المسار أو عدم اكتمالها في جلسة
Gateway الأساسية.
## الاختبار
يوفر OpenClaw اختبار Docker دخانيًا حتميًا لهذا الجسر:
```bash
pnpm test:docker:mcp-channels
```
هذا الاختبار الدخاني:
- يبدأ حاوية Gateway مهيأة مسبقًا
- يبدأ حاوية ثانية تشغّل `openclaw mcp serve`
- يتحقق من اكتشاف المحادثات، وقراءات النصوص، وقراءات بيانات تعريف المرفقات،
وسلوك قائمة انتظار الأحداث الحية، وتوجيه الإرسال الصادر
- يتحقق من إشعارات القنوات والأذونات بنمط Claude عبر
جسر MCP الحقيقي عبر stdio
هذه أسرع طريقة لإثبات أن الجسر يعمل من دون توصيل حساب
Telegram أو Discord أو iMessage حقيقي أثناء تشغيل الاختبار.
للحصول على سياق اختبار أوسع، راجع [الاختبار](/help/testing).
## استكشاف الأخطاء وإصلاحها
### لم يتم إرجاع أي محادثات
هذا يعني عادةً أن جلسة Gateway غير قابلة للتوجيه بالفعل. أكّد أن
الجلسة الأساسية تحتوي على بيانات تعريف مسار مخزنة للقناة/الموفر، والمستلم،
وبيانات تعريف الحساب/السلسلة الاختيارية.
### يفوّت `events_poll` أو `events_wait` الرسائل الأقدم
هذا متوقع. تبدأ قائمة الانتظار الحية عندما يتصل الجسر. اقرأ سجل
النصوص الأقدم باستخدام `messages_read`.
### لا تظهر إشعارات Claude
تحقق من كل ما يلي:
- أبقى العميل جلسة stdio MCP مفتوحة
- كانت قيمة `--claude-channel-mode` هي `on` أو `auto`
- يفهم العميل فعليًا طرق الإشعارات الخاصة بـ Claude
- حدثت الرسالة الواردة بعد اتصال الجسر
### الموافقات مفقودة
لا يعرض `permissions_list_open` سوى طلبات الموافقة التي تمت ملاحظتها بينما كان الجسر
متصلًا. وهو ليس API لسجل موافقات دائم.
## OpenClaw كسجل عميل MCP
هذا هو مسار `openclaw mcp list` و`show` و`set` و`unset`.
لا تكشف هذه الأوامر OpenClaw عبر MCP. بل تدير تعريفات خوادم MCP
المملوكة لـ OpenClaw ضمن `mcp.servers` في إعدادات OpenClaw.
تلك التعريفات المحفوظة مخصصة لبيئات التشغيل التي يقوم OpenClaw بتشغيلها أو إعدادها
لاحقًا، مثل Pi المضمّن ومكيفات وقت التشغيل الأخرى. يخزّن OpenClaw
التعريفات مركزيًا بحيث لا تحتاج تلك البيئات إلى الاحتفاظ بقوائم MCP
مكررة خاصة بها.
سلوك مهم:
- هذه الأوامر تقرأ أو تكتب إعدادات OpenClaw فقط
- لا تتصل بخادم MCP الهدف
- لا تتحقق مما إذا كان الأمر أو عنوان URL أو النقل البعيد
قابلًا للوصول الآن
- تقرر مكيّفات وقت التشغيل أشكال النقل التي تدعمها فعليًا
وقت التنفيذ
## تعريفات خوادم MCP المحفوظة
يخزن OpenClaw أيضًا سجلًا خفيفًا لخوادم MCP في الإعدادات للأسطح
التي تريد تعريفات MCP مُدارة من OpenClaw.
الأوامر:
- `openclaw mcp list`
- `openclaw mcp show [name]`
- `openclaw mcp set <name> <json>`
- `openclaw mcp unset <name>`
ملاحظات:
- يقوم `list` بترتيب أسماء الخوادم.
- يطبع `show` من دون اسم كائن خادم MCP المهيأ بالكامل.
- يتوقع `set` قيمة كائن JSON واحدة في سطر الأوامر.
- يفشل `unset` إذا لم يكن الخادم المسمى موجودًا.
أمثلة:
```bash
openclaw mcp list
openclaw mcp show context7 --json
openclaw mcp set context7 '{"command":"uvx","args":["context7-mcp"]}'
openclaw mcp set docs '{"url":"https://mcp.example.com"}'
openclaw mcp unset context7
```
مثال على شكل الإعدادات:
```json
{
"mcp": {
"servers": {
"context7": {
"command": "uvx",
"args": ["context7-mcp"]
},
"docs": {
"url": "https://mcp.example.com"
}
}
}
}
```
### نقل stdio
يشغّل عملية فرعية محلية ويتواصل عبر stdin/stdout.
| الحقل | الوصف |
| ----- | ----- |
| `command` | الملف التنفيذي المراد تشغيله (مطلوب) |
| `args` | مصفوفة وسائط سطر الأوامر |
| `env` | متغيرات بيئة إضافية |
| `cwd` / `workingDirectory` | دليل العمل الخاص بالعملية |
### نقل SSE / HTTP
يتصل بخادم MCP بعيد عبر HTTP Server-Sent Events.
| الحقل | الوصف |
| ----- | ----- |
| `url` | عنوان URL بخاصية HTTP أو HTTPS للخادم البعيد (مطلوب) |
| `headers` | خريطة مفتاح-قيمة اختيارية لترويسات HTTP (مثل رموز المصادقة) |
| `connectionTimeoutMs` | مهلة الاتصال لكل خادم بالمللي ثانية (اختياري) |
مثال:
```json
{
"mcp": {
"servers": {
"remote-tools": {
"url": "https://mcp.example.com",
"headers": {
"Authorization": "Bearer <token>"
}
}
}
}
}
```
تُحجب القيم الحساسة في `url` (userinfo) و`headers` في السجلات
ومخرجات الحالة.
### نقل streamable HTTP
يمثل `streamable-http` خيار نقل إضافيًا إلى جانب `sse` و`stdio`. ويستخدم بث HTTP للاتصال ثنائي الاتجاه مع خوادم MCP البعيدة.
| الحقل | الوصف |
| ----- | ----- |
| `url` | عنوان URL بخاصية HTTP أو HTTPS للخادم البعيد (مطلوب) |
| `transport` | اضبطه على `"streamable-http"` لاختيار هذا النقل؛ وعند حذفه يستخدم OpenClaw `sse` |
| `headers` | خريطة مفتاح-قيمة اختيارية لترويسات HTTP (مثل رموز المصادقة) |
| `connectionTimeoutMs` | مهلة الاتصال لكل خادم بالمللي ثانية (اختياري) |
مثال:
```json
{
"mcp": {
"servers": {
"streaming-tools": {
"url": "https://mcp.example.com/stream",
"transport": "streamable-http",
"connectionTimeoutMs": 10000,
"headers": {
"Authorization": "Bearer <token>"
}
}
}
}
}
```
تدير هذه الأوامر الإعدادات المحفوظة فقط. فهي لا تبدأ جسر القناة،
ولا تفتح جلسة عميل MCP حية، ولا تثبت أن الخادم الهدف قابل للوصول.
## القيود الحالية
توثق هذه الصفحة الجسر كما هو مشحون اليوم.
القيود الحالية:
- يعتمد اكتشاف المحادثات على بيانات تعريف مسار جلسة Gateway الموجودة
- لا يوجد بروتوكول دفع عام يتجاوز المكيّف الخاص بـ Claude
- لا توجد حتى الآن أدوات لتعديل الرسائل أو التفاعل معها
- يتصل نقل HTTP/SSE/streamable-http بخادم بعيد واحد؛ ولا يوجد upstream متعدد الإرسال بعد
- لا يتضمن `permissions_list_open` سوى الموافقات التي تمت ملاحظتها بينما كان الجسر
متصلًا

142
docs/ar/cli/memory.md Normal file
View File

@ -0,0 +1,142 @@
---
read_when:
- تريد فهرسة الذاكرة الدلالية أو البحث فيها
- أنت تصحح أخطاء توفر الذاكرة أو الفهرسة
- تريد ترقية الذاكرة قصيرة المدى المسترجعة إلى `MEMORY.md`
summary: مرجع CLI للأمر `openclaw memory` ‏(status/index/search/promote)
title: memory
x-i18n:
generated_at: "2026-04-05T12:38:43Z"
model: gpt-5.4
provider: openai
source_hash: a89e3a819737bb63521128ae63d9e25b5cd9db35c3ea4606d087a8ad48b41eab
source_path: cli/memory.md
workflow: 15
---
# `openclaw memory`
إدارة فهرسة الذاكرة الدلالية والبحث فيها.
يوفرها plugin الذاكرة النشط (الافتراضي: `memory-core`؛ اضبط `plugins.slots.memory = "none"` للتعطيل).
ذو صلة:
- مفهوم الذاكرة: [الذاكرة](/concepts/memory)
- Plugins: [Plugins](/tools/plugin)
## أمثلة
```bash
openclaw memory status
openclaw memory status --deep
openclaw memory status --fix
openclaw memory index --force
openclaw memory search "meeting notes"
openclaw memory search --query "deployment" --max-results 20
openclaw memory promote --limit 10 --min-score 0.75
openclaw memory promote --apply
openclaw memory promote --json --min-recall-count 0 --min-unique-queries 0
openclaw memory status --json
openclaw memory status --deep --index
openclaw memory status --deep --index --verbose
openclaw memory status --agent main
openclaw memory index --agent main --verbose
```
## الخيارات
`memory status` و`memory index`:
- `--agent <id>`: قصر النطاق على وكيل واحد. من دونه، تعمل هذه الأوامر لكل وكيل مكوَّن؛ وإذا لم تكن هناك قائمة وكلاء مكوّنة، فإنها تعود إلى الوكيل الافتراضي.
- `--verbose`: إصدار سجلات تفصيلية أثناء الفحوصات والفهرسة.
`memory status`:
- `--deep`: فحص توفر vector + embedding.
- `--index`: تشغيل إعادة فهرسة إذا كان المخزن متسخًا (ويتضمن `--deep`).
- `--fix`: إصلاح أقفال الاسترجاع القديمة وتطبيع بيانات الترقية الوصفية.
- `--json`: طباعة خرج JSON.
`memory index`:
- `--force`: فرض إعادة فهرسة كاملة.
`memory search`:
- إدخال الاستعلام: مرّر إما `[query]` الموضعي أو `--query <text>`.
- إذا تم توفير الاثنين، فإن `--query` هو الفائز.
- إذا لم يتم توفير أي منهما، يخرج الأمر بخطأ.
- `--agent <id>`: قصر النطاق على وكيل واحد (الافتراضي: الوكيل الافتراضي).
- `--max-results <n>`: تحديد عدد النتائج المعادة.
- `--min-score <n>`: تصفية المطابقات منخفضة الدرجات.
- `--json`: طباعة نتائج JSON.
`memory promote`:
معاينة وتطبيق ترقيات الذاكرة قصيرة المدى.
```bash
openclaw memory promote [--apply] [--limit <n>] [--include-promoted]
```
- `--apply` -- كتابة الترقيات إلى `MEMORY.md` (الافتراضي: المعاينة فقط).
- `--limit <n>` -- وضع حد أقصى لعدد المرشحين المعروضين.
- `--include-promoted` -- تضمين الإدخالات التي تمت ترقيتها بالفعل في الدورات السابقة.
الخيارات الكاملة:
- يرتّب المرشحين قصيري المدى من `memory/YYYY-MM-DD.md` باستخدام إشارات استرجاع موزونة (`frequency` و`relevance` و`query diversity` و`recency`).
- يستخدم أحداث الاسترجاع الملتقطة عندما يعيد `memory_search` نتائج من ذاكرة يومية.
- وضع dreaming التلقائي الاختياري: عندما تكون `plugins.entries.memory-core.config.dreaming.mode` هي `core` أو `deep` أو `rem`، يدير `memory-core` تلقائيًا مهمة cron تؤدي إلى الترقية في الخلفية (ولا حاجة إلى `openclaw cron add` يدوي).
- `--agent <id>`: قصر النطاق على وكيل واحد (الافتراضي: الوكيل الافتراضي).
- `--limit <n>`: الحد الأقصى للمرشحين الذين سيتم إرجاعهم/تطبيقهم.
- `--min-score <n>`: الحد الأدنى للدرجة الموزونة للترقية.
- `--min-recall-count <n>`: الحد الأدنى المطلوب لعدد مرات الاسترجاع لمرشح ما.
- `--min-unique-queries <n>`: الحد الأدنى المطلوب لعدد الاستعلامات المميزة لمرشح ما.
- `--apply`: إلحاق المرشحين المحددين إلى `MEMORY.md` ووضع علامة عليهم كمُرقّين.
- `--include-promoted`: تضمين المرشحين الذين تمت ترقيتهم بالفعل في الخرج.
- `--json`: طباعة خرج JSON.
## Dreaming (تجريبي)
Dreaming هو تمرير التأمل الليلي للذاكرة. يسمى "dreaming" لأن النظام يعيد زيارة ما تم استرجاعه خلال اليوم ويقرر ما الذي يستحق الاحتفاظ به على المدى الطويل.
- هو اختياري ومعطّل افتراضيًا.
- فعّله باستخدام `plugins.entries.memory-core.config.dreaming.mode`.
- يمكنك تبديل الأوضاع من الدردشة باستخدام `/dreaming off|core|rem|deep`. شغّل `/dreaming` (أو `/dreaming options`) لمعرفة ما يفعله كل وضع.
- عند تمكينه، ينشئ `memory-core` تلقائيًا مهمة cron مُدارة ويحافظ عليها.
- اضبط `dreaming.limit` على `0` إذا كنت تريد تمكين dreaming ولكن مع إيقاف الترقية التلقائية فعليًا.
- يستخدم الترتيب إشارات موزونة: تكرار الاسترجاع، وملاءمة الاسترجاع، وتنوع الاستعلامات، والحداثة الزمنية (تتلاشى عمليات الاسترجاع الحديثة بمرور الوقت).
- لا تحدث الترقية إلى `MEMORY.md` إلا عند استيفاء حدود الجودة، حتى تظل الذاكرة طويلة المدى عالية الإشارة بدلًا من جمع تفاصيل لمرة واحدة.
الإعدادات المسبقة الافتراضية للأوضاع:
- `core`: يوميًا عند `0 3 * * *`، و`minScore=0.75`، و`minRecallCount=3`، و`minUniqueQueries=2`
- `deep`: كل 12 ساعة (`0 */12 * * *`)، و`minScore=0.8`، و`minRecallCount=3`، و`minUniqueQueries=3`
- `rem`: كل 6 ساعات (`0 */6 * * *`)، و`minScore=0.85`، و`minRecallCount=4`، و`minUniqueQueries=3`
مثال:
```json
{
"plugins": {
"entries": {
"memory-core": {
"config": {
"dreaming": {
"mode": "core"
}
}
}
}
}
}
```
ملاحظات:
- يطبع `memory index --verbose` تفاصيل لكل مرحلة (المزوّد، والنموذج، والمصادر، ونشاط الدُفعات).
- يتضمن `memory status` أي مسارات إضافية مكوّنة عبر `memorySearch.extraPaths`.
- إذا كانت حقول مفاتيح API البعيدة الخاصة بالذاكرة النشطة فعليًا مكوّنة كـ SecretRefs، فإن الأمر يحل هذه القيم من لقطة gateway النشطة. وإذا لم يكن gateway متاحًا، يفشل الأمر سريعًا.
- ملاحظة حول اختلاف إصدار Gateway: يتطلب مسار هذا الأمر gateway يدعم `secrets.resolve`؛ تعيد البوابات الأقدم خطأ method غير معروف.
- يكون إيقاع dreaming افتراضيًا حسب الجدول المسبق لكل وضع. تجاوز الإيقاع باستخدام `plugins.entries.memory-core.config.dreaming.frequency` كتعبير cron (مثل `0 3 * * *`) واضبطه بدقة باستخدام `timezone` و`limit` و`minScore` و`minRecallCount` و`minUniqueQueries`.

307
docs/ar/cli/message.md Normal file
View File

@ -0,0 +1,307 @@
---
read_when:
- إضافة أو تعديل إجراءات الرسائل في CLI
- تغيير سلوك القنوات الصادر
summary: مرجع CLI للأمر `openclaw message` ‏(send + إجراءات القنوات)
title: message
x-i18n:
generated_at: "2026-04-05T12:38:59Z"
model: gpt-5.4
provider: openai
source_hash: b70f36189d028d59db25cd8b39d7c67883eaea71bea2358ee6314eec6cd2fa51
source_path: cli/message.md
workflow: 15
---
# `openclaw message`
أمر صادر واحد لإرسال الرسائل وإجراءات القنوات
(Discord/Google Chat/iMessage/Matrix/Mattermost (plugin)/Microsoft Teams/Signal/Slack/Telegram/WhatsApp).
## الاستخدام
```
openclaw message <subcommand> [flags]
```
اختيار القناة:
- يكون `--channel` مطلوبًا إذا كانت هناك أكثر من قناة واحدة مهيأة.
- إذا كانت هناك قناة واحدة فقط مهيأة، فإنها تصبح القيمة الافتراضية.
- القيم: `discord|googlechat|imessage|matrix|mattermost|msteams|signal|slack|telegram|whatsapp` ‏(يتطلب Mattermost وجود plugin)
تنسيقات الهدف (`--target`):
- WhatsApp: ‏E.164 أو group JID
- Telegram: ‏chat id أو `@username`
- Discord: ‏`channel:<id>` أو `user:<id>` ‏(أو الإشارة `<@id>`؛ وتُعامل المعرّفات الرقمية الخام على أنها قنوات)
- Google Chat: ‏`spaces/<spaceId>` أو `users/<userId>`
- Slack: ‏`channel:<id>` أو `user:<id>` ‏(يُقبل معرّف القناة الخام)
- Mattermost (plugin): ‏`channel:<id>` أو `user:<id>` أو `@username` ‏(تُعامل المعرّفات المجردة على أنها قنوات)
- Signal: ‏`+E.164` أو `group:<id>` أو `signal:+E.164` أو `signal:group:<id>` أو `username:<name>`/`u:<name>`
- iMessage: ‏handle أو `chat_id:<id>` أو `chat_guid:<guid>` أو `chat_identifier:<id>`
- Matrix: ‏`@user:server` أو `!room:server` أو `#alias:server`
- Microsoft Teams: معرّف المحادثة (`19:...@thread.tacv2`) أو `conversation:<id>` أو `user:<aad-object-id>`
البحث بالاسم:
- بالنسبة إلى المزوّدين المدعومين (Discord/Slack/إلخ)، يتم حل أسماء القنوات مثل `Help` أو `#help` عبر ذاكرة التخزين المؤقت للدليل.
- عند غياب الإدخال من الذاكرة المؤقتة، سيحاول OpenClaw إجراء بحث مباشر في الدليل عندما يدعم المزوّد ذلك.
## الأعلام الشائعة
- `--channel <name>`
- `--account <id>`
- `--target <dest>` ‏(القناة أو المستخدم المستهدف للإرسال/poll/read/إلخ)
- `--targets <name>` ‏(قابل للتكرار؛ للبث فقط)
- `--json`
- `--dry-run`
- `--verbose`
## سلوك SecretRef
- يقوم `openclaw message` بحل SecretRefs المدعومة للقنوات قبل تنفيذ الإجراء المحدد.
- يتم حصر الحل في هدف الإجراء النشط عندما يكون ذلك ممكنًا:
- على نطاق القناة عند ضبط `--channel` ‏(أو عند استنتاجه من الأهداف ذات البادئة مثل `discord:...`)
- على نطاق الحساب عند ضبط `--account` ‏(أسطح القناة العامة + أسطح الحساب المحدد)
- عند حذف `--account`، لا يفرض OpenClaw نطاق SecretRef لحساب `default`
- لا تمنع SecretRefs غير المحلولة في القنوات غير المرتبطة إجراء رسالة مستهدفًا.
- إذا كان SecretRef الخاص بالقناة/الحساب المحدد غير محلول، يفشل الأمر بشكل مغلق لذلك الإجراء.
## الإجراءات
### الأساسية
- `send`
- القنوات: WhatsApp/Telegram/Discord/Google Chat/Slack/Mattermost (plugin)/Signal/iMessage/Matrix/Microsoft Teams
- المطلوب: `--target`، بالإضافة إلى `--message` أو `--media`
- الاختياري: `--media` و`--interactive` و`--buttons` و`--components` و`--card` و`--reply-to` و`--thread-id` و`--gif-playback` و`--force-document` و`--silent`
- الحمولات التفاعلية المشتركة: يرسل `--interactive` حمولة JSON تفاعلية أصلية للقناة عندما تكون مدعومة
- Telegram فقط: `--buttons` ‏(يتطلب أن يسمح `channels.telegram.capabilities.inlineButtons` بذلك)
- Telegram فقط: `--force-document` ‏(إرسال الصور وملفات GIF كمستندات لتجنب ضغط Telegram)
- Telegram فقط: `--thread-id` ‏(معرّف موضوع المنتدى)
- Slack فقط: `--thread-id` ‏(الطابع الزمني للسلسلة؛ ويستخدم `--reply-to` الحقل نفسه)
- Discord فقط: حمولة JSON لـ `--components`
- القنوات التي تدعم Adaptive Card: حمولة JSON لـ `--card` عندما تكون مدعومة
- Telegram + Discord: ‏`--silent`
- WhatsApp فقط: `--gif-playback`
- `poll`
- القنوات: WhatsApp/Telegram/Discord/Matrix/Microsoft Teams
- المطلوب: `--target` و`--poll-question` و`--poll-option` ‏(قابل للتكرار)
- الاختياري: `--poll-multi`
- Discord فقط: `--poll-duration-hours` و`--silent` و`--message`
- Telegram فقط: `--poll-duration-seconds` ‏(5-600) و`--silent` و`--poll-anonymous` / `--poll-public` و`--thread-id`
- `react`
- القنوات: Discord/Google Chat/Slack/Telegram/WhatsApp/Signal/Matrix
- المطلوب: `--message-id` و`--target`
- الاختياري: `--emoji` و`--remove` و`--participant` و`--from-me` و`--target-author` و`--target-author-uuid`
- ملاحظة: يتطلب `--remove` وجود `--emoji` ‏(احذف `--emoji` لمسح تفاعلاتك الخاصة عند الدعم؛ راجع /tools/reactions)
- WhatsApp فقط: `--participant` و`--from-me`
- تفاعلات مجموعات Signal: يتطلب `--target-author` أو `--target-author-uuid`
- `reactions`
- القنوات: Discord/Google Chat/Slack/Matrix
- المطلوب: `--message-id` و`--target`
- الاختياري: `--limit`
- `read`
- القنوات: Discord/Slack/Matrix
- المطلوب: `--target`
- الاختياري: `--limit` و`--before` و`--after`
- Discord فقط: `--around`
- `edit`
- القنوات: Discord/Slack/Matrix
- المطلوب: `--message-id` و`--message` و`--target`
- `delete`
- القنوات: Discord/Slack/Telegram/Matrix
- المطلوب: `--message-id` و`--target`
- `pin` / `unpin`
- القنوات: Discord/Slack/Matrix
- المطلوب: `--message-id` و`--target`
- `pins` ‏(عرض القائمة)
- القنوات: Discord/Slack/Matrix
- المطلوب: `--target`
- `permissions`
- القنوات: Discord/Matrix
- المطلوب: `--target`
- Matrix فقط: متاح عند تمكين تشفير Matrix والسماح بإجراءات التحقق
- `search`
- القنوات: Discord
- المطلوب: `--guild-id` و`--query`
- الاختياري: `--channel-id` و`--channel-ids` ‏(قابل للتكرار) و`--author-id` و`--author-ids` ‏(قابل للتكرار) و`--limit`
### السلاسل
- `thread create`
- القنوات: Discord
- المطلوب: `--thread-name` و`--target` ‏(معرّف القناة)
- الاختياري: `--message-id` و`--message` و`--auto-archive-min`
- `thread list`
- القنوات: Discord
- المطلوب: `--guild-id`
- الاختياري: `--channel-id` و`--include-archived` و`--before` و`--limit`
- `thread reply`
- القنوات: Discord
- المطلوب: `--target` ‏(معرّف السلسلة) و`--message`
- الاختياري: `--media` و`--reply-to`
### الرموز التعبيرية
- `emoji list`
- Discord: ‏`--guild-id`
- Slack: لا توجد أعلام إضافية
- `emoji upload`
- القنوات: Discord
- المطلوب: `--guild-id` و`--emoji-name` و`--media`
- الاختياري: `--role-ids` ‏(قابل للتكرار)
### الملصقات
- `sticker send`
- القنوات: Discord
- المطلوب: `--target` و`--sticker-id` ‏(قابل للتكرار)
- الاختياري: `--message`
- `sticker upload`
- القنوات: Discord
- المطلوب: `--guild-id` و`--sticker-name` و`--sticker-desc` و`--sticker-tags` و`--media`
### الأدوار / القنوات / الأعضاء / الصوت
- `role info` ‏(Discord): ‏`--guild-id`
- `role add` / `role remove` ‏(Discord): ‏`--guild-id` و`--user-id` و`--role-id`
- `channel info` ‏(Discord): ‏`--target`
- `channel list` ‏(Discord): ‏`--guild-id`
- `member info` ‏(Discord/Slack): ‏`--user-id` ‏(+ `--guild-id` لـ Discord)
- `voice status` ‏(Discord): ‏`--guild-id` و`--user-id`
### الأحداث
- `event list` ‏(Discord): ‏`--guild-id`
- `event create` ‏(Discord): ‏`--guild-id` و`--event-name` و`--start-time`
- الاختياري: `--end-time` و`--desc` و`--channel-id` و`--location` و`--event-type`
### الإشراف (Discord)
- `timeout`: ‏`--guild-id` و`--user-id` ‏(اختياري `--duration-min` أو `--until`؛ احذف كليهما لإزالة timeout)
- `kick`: ‏`--guild-id` و`--user-id` ‏(+ `--reason`)
- `ban`: ‏`--guild-id` و`--user-id` ‏(+ `--delete-days` و`--reason`)
- يدعم `timeout` أيضًا `--reason`
### البث
- `broadcast`
- القنوات: أي قناة مهيأة؛ استخدم `--channel all` لاستهداف جميع المزوّدين
- المطلوب: `--targets <target...>`
- الاختياري: `--message` و`--media` و`--dry-run`
## أمثلة
إرسال رد في Discord:
```
openclaw message send --channel discord \
--target channel:123 --message "hi" --reply-to 456
```
إرسال رسالة Discord مع components:
```
openclaw message send --channel discord \
--target channel:123 --message "Choose:" \
--components '{"text":"Choose a path","blocks":[{"type":"actions","buttons":[{"label":"Approve","style":"success"},{"label":"Decline","style":"danger"}]}]}'
```
راجع [Discord components](/channels/discord#interactive-components) للحصول على المخطط الكامل.
إرسال حمولة تفاعلية مشتركة:
```bash
openclaw message send --channel googlechat --target spaces/AAA... \
--message "Choose:" \
--interactive '{"text":"Choose a path","blocks":[{"type":"actions","buttons":[{"label":"Approve"},{"label":"Decline"}]}]}'
```
إنشاء poll في Discord:
```
openclaw message poll --channel discord \
--target channel:123 \
--poll-question "Snack?" \
--poll-option Pizza --poll-option Sushi \
--poll-multi --poll-duration-hours 48
```
إنشاء poll في Telegram ‏(إغلاق تلقائي بعد دقيقتين):
```
openclaw message poll --channel telegram \
--target @mychat \
--poll-question "Lunch?" \
--poll-option Pizza --poll-option Sushi \
--poll-duration-seconds 120 --silent
```
إرسال رسالة استباقية في Teams:
```
openclaw message send --channel msteams \
--target conversation:19:abc@thread.tacv2 --message "hi"
```
إنشاء poll في Teams:
```
openclaw message poll --channel msteams \
--target conversation:19:abc@thread.tacv2 \
--poll-question "Lunch?" \
--poll-option Pizza --poll-option Sushi
```
إضافة تفاعل في Slack:
```
openclaw message react --channel slack \
--target C123 --message-id 456 --emoji "✅"
```
إضافة تفاعل في مجموعة Signal:
```
openclaw message react --channel signal \
--target signal:group:abc123 --message-id 1737630212345 \
--emoji "✅" --target-author-uuid 123e4567-e89b-12d3-a456-426614174000
```
إرسال أزرار inline في Telegram:
```
openclaw message send --channel telegram --target @mychat --message "Choose:" \
--buttons '[ [{"text":"Yes","callback_data":"cmd:yes"}], [{"text":"No","callback_data":"cmd:no"}] ]'
```
إرسال Adaptive Card في Teams:
```bash
openclaw message send --channel msteams \
--target conversation:19:abc@thread.tacv2 \
--card '{"type":"AdaptiveCard","version":"1.5","body":[{"type":"TextBlock","text":"Status update"}]}'
```
إرسال صورة Telegram كمستند لتجنب الضغط:
```bash
openclaw message send --channel telegram --target @mychat \
--media ./diagram.png --force-document
```

141
docs/ar/cli/models.md Normal file
View File

@ -0,0 +1,141 @@
---
read_when:
- تريد تغيير النماذج الافتراضية أو عرض حالة مصادقة المزوّد
- تريد فحص النماذج/المزوّدات المتاحة وتصحيح ملفات تعريف المصادقة
summary: مرجع CLI للأمر `openclaw models` (status/list/set/scan، والأسماء البديلة، والبدائل الاحتياطية، والمصادقة)
title: models
x-i18n:
generated_at: "2026-04-05T12:38:51Z"
model: gpt-5.4
provider: openai
source_hash: 04ba33181d49b6bbf3b5d5fa413aa6b388c9f29fb9d4952055d68c79f7bcfea0
source_path: cli/models.md
workflow: 15
---
# `openclaw models`
اكتشاف النماذج وفحصها وإعدادها (النموذج الافتراضي، والبدائل الاحتياطية، وملفات تعريف المصادقة).
ذو صلة:
- المزوّدون + النماذج: [النماذج](/providers/models)
- إعداد مصادقة المزوّد: [البدء](/ar/start/getting-started)
## الأوامر الشائعة
```bash
openclaw models status
openclaw models list
openclaw models set <model-or-alias>
openclaw models scan
```
يعرض `openclaw models status` القيم الافتراضية/الاحتياطية المحلولة بالإضافة إلى نظرة عامة على المصادقة.
وعندما تكون لقطات استخدام المزوّد متاحة، يتضمن قسم حالة OAuth/API key
نوافذ استخدام المزوّد ولقطات الحصة.
مزوّدو نوافذ الاستخدام الحاليون: Anthropic وGitHub Copilot وGemini CLI وOpenAI
Codex وMiniMax وXiaomi وz.ai. تأتي مصادقة الاستخدام من خطافات خاصة بالمزوّد
عند توفرها؛ وإلا يعود OpenClaw إلى مطابقة بيانات اعتماد OAuth/API-key
من ملفات تعريف المصادقة أو البيئة أو الإعداد.
أضف `--probe` لتشغيل مجسات مصادقة مباشرة مقابل كل ملف تعريف مزوّد مُعد.
المجسات هي طلبات حقيقية (وقد تستهلك tokens وتؤدي إلى حدود معدل).
استخدم `--agent <id>` لفحص حالة النموذج/المصادقة لوكيل مُعد. وعند عدم تحديده،
يستخدم الأمر `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR` إذا كان مضبوطًا، وإلا
يستخدم الوكيل الافتراضي المُعد.
يمكن أن تأتي صفوف المجسات من ملفات تعريف المصادقة أو بيانات اعتماد البيئة أو `models.json`.
ملاحظات:
- يقبل `models set <model-or-alias>` التنسيق `provider/model` أو اسمًا بديلًا.
- تُحلّل مراجع النماذج عبر التقسيم عند **أول** `/`. وإذا كان معرّف النموذج يتضمن `/` (بنمط OpenRouter)، فأدرج بادئة المزوّد (مثال: `openrouter/moonshotai/kimi-k2`).
- إذا حذفت المزوّد، فسيحل OpenClaw الإدخال أولًا على أنه اسم بديل، ثم
على أنه تطابق فريد لمزوّد مُعد لذلك المعرّف الدقيق للنموذج، وبعدها فقط
يعود إلى المزوّد الافتراضي المُعد مع تحذير إيقاف.
وإذا لم يعد ذلك المزوّد يعرض النموذج الافتراضي المُعد، فسيعود OpenClaw
إلى أول مزوّد/نموذج مُعد بدلًا من إظهار
قيمة افتراضية قديمة من مزوّد محذوف.
- قد يعرض `models status` ‏`marker(<value>)` في مخرجات المصادقة للعناصر النائبة غير السرية (مثل `OPENAI_API_KEY` و`secretref-managed` و`minimax-oauth` و`oauth:chutes` و`ollama-local`) بدلًا من إخفائها كأسرار.
### `models status`
الخيارات:
- `--json`
- `--plain`
- `--check` ‏(رمز الخروج 1=منتهي/مفقود، 2=قارب على الانتهاء)
- `--probe` ‏(مجس مباشر لملفات تعريف المصادقة المُعدة)
- `--probe-provider <name>` ‏(فحص مزوّد واحد)
- `--probe-profile <id>` ‏(قابل للتكرار أو مفصول بفواصل لمعرّفات الملفات)
- `--probe-timeout <ms>`
- `--probe-concurrency <n>`
- `--probe-max-tokens <n>`
- `--agent <id>` ‏(معرّف وكيل مُعد؛ يتجاوز `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR`)
فئات حالة المجس:
- `ok`
- `auth`
- `rate_limit`
- `billing`
- `timeout`
- `format`
- `unknown`
- `no_model`
حالات التفاصيل/رموز السبب المتوقعة في المجس:
- `excluded_by_auth_order`: يوجد ملف تعريف مخزّن، لكن
`auth.order.<provider>` الصريح استبعده، لذلك يبلغ المجس عن هذا الاستبعاد
بدلًا من تجربته.
- `missing_credential`, `invalid_expires`, `expired`, `unresolved_ref`:
ملف التعريف موجود لكنه غير مؤهل/غير قابل للحل.
- `no_model`: مصادقة المزوّد موجودة، لكن OpenClaw لم يتمكن من حل مرشح نموذج قابل للفحص لذلك المزوّد.
## الأسماء البديلة + البدائل الاحتياطية
```bash
openclaw models aliases list
openclaw models fallbacks list
```
## ملفات تعريف المصادقة
```bash
openclaw models auth add
openclaw models auth login --provider <id>
openclaw models auth setup-token --provider <id>
openclaw models auth paste-token
```
`models auth add` هو مساعد المصادقة التفاعلي. ويمكنه تشغيل تدفق مصادقة مزوّد
(OAuth/API key) أو إرشادك إلى لصق token يدويًا، حسب
المزوّد الذي تختاره.
يشغّل `models auth login` تدفق مصادقة لمكون إضافي خاص بالمزوّد
(OAuth/API key). استخدم `openclaw plugins list` لمعرفة المزوّدين المثبتين.
أمثلة:
```bash
openclaw models auth login --provider anthropic --method cli --set-default
openclaw models auth login --provider openai-codex --set-default
```
ملاحظات:
- يعيد `login --provider anthropic --method cli --set-default` استخدام تسجيل
دخول Claude CLI محلي، ويعيد كتابة مسار النموذج الافتراضي الرئيسي لـ Anthropic إلى مرجع
قانوني `claude-cli/claude-*`.
- يظل `setup-token` و`paste-token` أوامر tokens عامة للمزوّدين
الذين يوفّرون أساليب مصادقة معتمدة على token.
- يتطلب `setup-token` طرفية تفاعلية ويشغّل أسلوب مصادقة token الخاص بالمزوّد
(ويفترض افتراضيًا أسلوب `setup-token` لذلك المزوّد عندما يوفّره).
- يقبل `paste-token` سلسلة token مُولَّدة في مكان آخر أو من عملية أتمتة.
- يتطلب `paste-token` الخيار `--provider`، ويطلب قيمة token، ويكتبها
إلى معرّف ملف التعريف الافتراضي `<provider>:manual` ما لم تمرر
`--profile-id`.
- يخزن `paste-token --expires-in <duration>` وقت انتهاء token مطلقًا انطلاقًا من
مدة نسبية مثل `365d` أو `12h`.
- ملاحظة فوترة Anthropic: نعتقد أن Claude Code CLI الاحتياطي مسموح على الأرجح لعمليات الأتمتة المحلية التي يديرها المستخدم استنادًا إلى وثائق CLI العامة من Anthropic. ومع ذلك، فإن سياسة Anthropic الخاصة بأحزمة الأطراف الثالثة تخلق قدرًا كافيًا من الغموض بشأن الاستخدام المدعوم بالاشتراك في المنتجات الخارجية، لذلك لا نوصي به للإنتاج. كما أبلغت Anthropic مستخدمي OpenClaw في **4 أبريل 2026 الساعة 12:00 ظهرًا بتوقيت PT / 8:00 مساءً بتوقيت BST** أن مسار تسجيل الدخول إلى Claude ضمن **OpenClaw** يُعد استخدامًا لحزمة طرف ثالث ويتطلب **Extra Usage** تُحتسب بشكل منفصل عن الاشتراك.
- أصبح `setup-token` / `paste-token` في Anthropic متاحين مرة أخرى كمسار OpenClaw قديم/يدوي. استخدمهما مع توقع أن Anthropic أبلغت مستخدمي OpenClaw أن هذا المسار يتطلب **Extra Usage**.

144
docs/ar/cli/node.md Normal file
View File

@ -0,0 +1,144 @@
---
read_when:
- تشغيل مضيف العقدة headless
- إقران عقدة غير macOS لأجل system.run
summary: مرجع CLI للأمر `openclaw node` (مضيف العقدة headless)
title: node
x-i18n:
generated_at: "2026-04-05T12:38:57Z"
model: gpt-5.4
provider: openai
source_hash: 6123b33ec46f2b85f2c815947435ac91bbe84456165ff0e504453356da55b46d
source_path: cli/node.md
workflow: 15
---
# `openclaw node`
شغّل **مضيف عقدة headless** يتصل بـ Gateway WebSocket ويكشف
`system.run` / `system.which` على هذا الجهاز.
## لماذا تستخدم مضيف عقدة؟
استخدم مضيف عقدة عندما تريد أن تقوم الوكلاء **بتشغيل الأوامر على أجهزة أخرى** في
شبكتك من دون تثبيت تطبيق macOS مصاحب كامل هناك.
حالات الاستخدام الشائعة:
- تشغيل الأوامر على أجهزة Linux/Windows بعيدة (خوادم بناء، أجهزة مختبر، NAS).
- إبقاء exec **ضمن صندوق حماية** على البوابة، مع تفويض عمليات التشغيل المعتمدة إلى مضيفين آخرين.
- توفير هدف تنفيذ خفيف وheadless لعمليات الأتمتة أو عقد CI.
يظل التنفيذ محميًا بواسطة **موافقات exec** وقوائم السماح لكل وكيل على
مضيف العقدة، بحيث يمكنك إبقاء الوصول إلى الأوامر محدودًا وصريحًا.
## وكيل المتصفح (بدون إعداد)
تعلن مضيفات العقد تلقائيًا عن وكيل متصفح إذا لم يتم
تعطيل `browser.enabled` على العقدة. يتيح هذا للوكيل استخدام أتمتة المتصفح على تلك العقدة
من دون إعداد إضافي.
بشكل افتراضي، يكشف الوكيل عن سطح ملف تعريف المتصفح العادي للعقدة. وإذا
ضبطت `nodeHost.browserProxy.allowProfiles`، يصبح الوكيل مقيِّدًا:
يتم رفض استهداف ملفات التعريف غير الموجودة في قائمة السماح، كما تُحظر
مسارات إنشاء/حذف ملفات التعريف الدائمة عبر الوكيل.
عطّله على العقدة عند الحاجة:
```json5
{
nodeHost: {
browserProxy: {
enabled: false,
},
},
}
```
## التشغيل (الواجهة الأمامية)
```bash
openclaw node run --host <gateway-host> --port 18789
```
الخيارات:
- `--host <host>`: مضيف Gateway WebSocket (الافتراضي: `127.0.0.1`)
- `--port <port>`: منفذ Gateway WebSocket (الافتراضي: `18789`)
- `--tls`: استخدام TLS لاتصال البوابة
- `--tls-fingerprint <sha256>`: بصمة شهادة TLS المتوقعة (`sha256`)
- `--node-id <id>`: تجاوز معرّف العقدة (يمسح رمز الاقتران)
- `--display-name <name>`: تجاوز الاسم المعروض للعقدة
## مصادقة البوابة لمضيف العقدة
يقوم `openclaw node run` و`openclaw node install` بتحليل مصادقة البوابة من الإعداد/البيئة (لا توجد علامات `--token`/`--password` على أوامر node):
- يتم التحقق أولًا من `OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD`.
- ثم الرجوع إلى الإعداد المحلي: `gateway.auth.token` / `gateway.auth.password`.
- في الوضع المحلي، لا يرث مضيف العقدة عمدًا `gateway.remote.token` / `gateway.remote.password`.
- إذا تم إعداد `gateway.auth.token` / `gateway.auth.password` صراحةً عبر SecretRef وكان غير محلول، يفشل تحليل مصادقة العقدة بشكل مغلق (من دون رجوع بعيد يخفي المشكلة).
- في `gateway.mode=remote`، تكون حقول العميل البعيد (`gateway.remote.token` / `gateway.remote.password`) مؤهلة أيضًا وفق قواعد أسبقية الوضع البعيد.
- لا يحترم تحليل مصادقة مضيف العقدة إلا متغيرات البيئة `OPENCLAW_GATEWAY_*`.
## الخدمة (الخلفية)
ثبّت مضيف عقدة headless كخدمة مستخدم.
```bash
openclaw node install --host <gateway-host> --port 18789
```
الخيارات:
- `--host <host>`: مضيف Gateway WebSocket (الافتراضي: `127.0.0.1`)
- `--port <port>`: منفذ Gateway WebSocket (الافتراضي: `18789`)
- `--tls`: استخدام TLS لاتصال البوابة
- `--tls-fingerprint <sha256>`: بصمة شهادة TLS المتوقعة (`sha256`)
- `--node-id <id>`: تجاوز معرّف العقدة (يمسح رمز الاقتران)
- `--display-name <name>`: تجاوز الاسم المعروض للعقدة
- `--runtime <runtime>`: بيئة تشغيل الخدمة (`node` أو `bun`)
- `--force`: إعادة التثبيت/الاستبدال إذا كان مثبتًا بالفعل
إدارة الخدمة:
```bash
openclaw node status
openclaw node stop
openclaw node restart
openclaw node uninstall
```
استخدم `openclaw node run` للحصول على مضيف عقدة في الواجهة الأمامية (من دون خدمة).
تقبل أوامر الخدمة الخيار `--json` لإخراج قابل للقراءة آليًا.
## الاقتران
ينشئ أول اتصال طلب اقتران جهاز معلقًا (`role: node`) على البوابة.
وافق عليه عبر:
```bash
openclaw devices list
openclaw devices approve <requestId>
```
إذا أعادت العقدة محاولة الاقتران مع تفاصيل مصادقة متغيرة (دور/نطاقات/مفتاح عام)،
فسيتم استبدال الطلب المعلق السابق وإنشاء `requestId` جديد.
شغّل `openclaw devices list` مرة أخرى قبل الموافقة.
يخزّن مضيف العقدة معرّف العقدة، والرمز، والاسم المعروض، ومعلومات اتصال البوابة في
`~/.openclaw/node.json`.
## موافقات exec
يتم تقييد `system.run` بواسطة موافقات exec المحلية:
- `~/.openclaw/exec-approvals.json`
- [موافقات Exec](/tools/exec-approvals)
- `openclaw approvals --node <id|name|ip>` (للتعديل من البوابة)
بالنسبة إلى تنفيذ العقدة غير المتزامن المعتمد، يقوم OpenClaw بإعداد `systemRunPlan`
قياسي قبل المطالبة. ثم تعيد عملية إعادة توجيه `system.run` المعتمدة لاحقًا استخدام تلك
الخطة المخزنة، لذلك يتم رفض التعديلات على حقول command/cwd/session بعد إنشاء
طلب الموافقة بدلًا من تغيير ما ستنفذه العقدة.

73
docs/ar/cli/nodes.md Normal file
View File

@ -0,0 +1,73 @@
---
read_when:
- أنت تدير nodes مقترنة (كاميرات، شاشة، canvas)
- تحتاج إلى الموافقة على الطلبات أو استدعاء أوامر node
summary: مرجع CLI للأمر `openclaw nodes` ‏(status وpairing وinvoke وcamera/canvas/screen)
title: nodes
x-i18n:
generated_at: "2026-04-05T12:38:54Z"
model: gpt-5.4
provider: openai
source_hash: 1ce3095591c4623ad18e3eca8d8083e5c10266fbf94afea2d025f0ba8093a175
source_path: cli/nodes.md
workflow: 15
---
# `openclaw nodes`
إدارة nodes المقترنة (الأجهزة) واستدعاء قدرات node.
ذو صلة:
- نظرة عامة على Nodes: [Nodes](/nodes)
- الكاميرا: [Camera nodes](/nodes/camera)
- الصور: [Image nodes](/nodes/images)
الخيارات الشائعة:
- `--url` و`--token` و`--timeout` و`--json`
## الأوامر الشائعة
```bash
openclaw nodes list
openclaw nodes list --connected
openclaw nodes list --last-connected 24h
openclaw nodes pending
openclaw nodes approve <requestId>
openclaw nodes reject <requestId>
openclaw nodes rename --node <id|name|ip> --name <displayName>
openclaw nodes status
openclaw nodes status --connected
openclaw nodes status --last-connected 24h
```
يطبع `nodes list` جداول الطلبات المعلقة/المقترنة. تتضمن الصفوف المقترنة أحدث مدة منذ الاتصال (Last Connect).
استخدم `--connected` لإظهار nodes المتصلة حاليًا فقط. استخدم `--last-connected <duration>` من أجل
التصفية إلى nodes التي اتصلت خلال مدة معينة (مثل `24h` أو `7d`).
ملاحظة الموافقة:
- يحتاج `openclaw nodes pending` فقط إلى نطاق pairing.
- يرث `openclaw nodes approve <requestId>` متطلبات النطاق الإضافية من
الطلب المعلق:
- طلب بلا أوامر: pairing فقط
- أوامر node غير التنفيذية: pairing + write
- `system.run` / `system.run.prepare` / `system.which`: pairing + admin
## الاستدعاء
```bash
openclaw nodes invoke --node <id|name|ip> --command <command> --params <json>
```
علامات الاستدعاء:
- `--params <json>`: سلسلة كائن JSON ‏(الافتراضي `{}`).
- `--invoke-timeout <ms>`: مهلة استدعاء node ‏(الافتراضي `15000`).
- `--idempotency-key <key>`: مفتاح idempotency اختياري.
- يتم حظر `system.run` و`system.run.prepare` هنا؛ استخدم أداة `exec` مع `host=node` لتنفيذ shell.
لتنفيذ shell على node، استخدم أداة `exec` مع `host=node` بدلًا من `openclaw nodes run`.
أصبحت واجهة CLI الخاصة بـ `nodes` الآن مركزة على القدرات: RPC مباشر عبر `nodes invoke`، بالإضافة إلى pairing والكاميرا
والشاشة والموقع وcanvas والإشعارات.

178
docs/ar/cli/onboard.md Normal file
View File

@ -0,0 +1,178 @@
---
read_when:
- تريد إعدادًا موجّهًا لـ gateway ومساحة العمل والمصادقة والقنوات وSkills
summary: مرجع CLI للأمر `openclaw onboard` (الإعداد التفاعلي الأولي)
title: onboard
x-i18n:
generated_at: "2026-04-05T12:39:14Z"
model: gpt-5.4
provider: openai
source_hash: 6db61c8002c9e82e48ff44f72e176b58ad85fad5cb8434687455ed40add8cc2a
source_path: cli/onboard.md
workflow: 15
---
# `openclaw onboard`
الإعداد التفاعلي الأولي لإعداد Gateway محلي أو بعيد.
## أدلة ذات صلة
- مركز إعداد CLI الأولي: [Onboarding (CLI)](/ar/start/wizard)
- نظرة عامة على الإعداد الأولي: [Onboarding Overview](/start/onboarding-overview)
- مرجع إعداد CLI الأولي: [CLI Setup Reference](/start/wizard-cli-reference)
- أتمتة CLI: [CLI Automation](/start/wizard-cli-automation)
- الإعداد الأولي على macOS: [Onboarding (macOS App)](/start/onboarding)
## أمثلة
```bash
openclaw onboard
openclaw onboard --flow quickstart
openclaw onboard --flow manual
openclaw onboard --mode remote --remote-url wss://gateway-host:18789
```
بالنسبة إلى أهداف `ws://` ذات النص الصريح على الشبكات الخاصة (الشبكات الموثوقة فقط)، اضبط
`OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` في بيئة عملية الإعداد الأولي.
مزود مخصص غير تفاعلي:
```bash
openclaw onboard --non-interactive \
--auth-choice custom-api-key \
--custom-base-url "https://llm.example.com/v1" \
--custom-model-id "foo-large" \
--custom-api-key "$CUSTOM_API_KEY" \
--secret-input-mode plaintext \
--custom-compatibility openai
```
تكون `--custom-api-key` اختيارية في الوضع غير التفاعلي. إذا لم تُمرَّر، يتحقق الإعداد الأولي من `CUSTOM_API_KEY`.
Ollama غير التفاعلي:
```bash
openclaw onboard --non-interactive \
--auth-choice ollama \
--custom-base-url "http://ollama-host:11434" \
--custom-model-id "qwen3.5:27b" \
--accept-risk
```
القيمة الافتراضية لـ `--custom-base-url` هي `http://127.0.0.1:11434`. وتكون `--custom-model-id` اختيارية؛ وإذا لم تُمرَّر، يستخدم الإعداد الأولي القيم الافتراضية المقترحة من Ollama. كما تعمل هنا أيضًا معرّفات النماذج السحابية مثل `kimi-k2.5:cloud`.
خزّن مفاتيح المزوّد كمراجع بدلًا من نص صريح:
```bash
openclaw onboard --non-interactive \
--auth-choice openai-api-key \
--secret-input-mode ref \
--accept-risk
```
مع `--secret-input-mode ref`، يكتب الإعداد الأولي مراجع مدعومة بـ env بدلًا من قيم المفاتيح النصية الصريحة.
وبالنسبة إلى المزوّدين المدعومين بملفات تعريف المصادقة، يكتب هذا إدخالات `keyRef`؛ أما بالنسبة إلى المزوّدين المخصصين، فيكتب `models.providers.<id>.apiKey` كمرجع env (على سبيل المثال `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`).
عقد وضع `ref` غير التفاعلي:
- اضبط متغير env الخاص بالمزوّد في بيئة عملية الإعداد الأولي (على سبيل المثال `OPENAI_API_KEY`).
- لا تمرر علامات المفاتيح المضمنة (مثل `--openai-api-key`) إلا إذا كان متغير env هذا مضبوطًا أيضًا.
- إذا مُرِّرت علامة مفتاح مضمن من دون متغير env المطلوب، يفشل الإعداد الأولي بسرعة مع إرشادات.
خيارات token الخاصة بـ gateway في الوضع غير التفاعلي:
- `--gateway-auth token --gateway-token <token>` يخزن token نصيًا صريحًا.
- `--gateway-auth token --gateway-token-ref-env <name>` يخزن `gateway.auth.token` كمرجع env SecretRef.
- لا يمكن استخدام `--gateway-token` و`--gateway-token-ref-env` معًا.
- يتطلب `--gateway-token-ref-env` متغير env غير فارغ في بيئة عملية الإعداد الأولي.
- مع `--install-daemon`، عندما تتطلب مصادقة token وجود token، يتم التحقق من tokens الخاصة بـ gateway المُدارة بواسطة SecretRef ولكن لا تُحفَظ كنص صريح محلول ضمن بيانات تعريف بيئة خدمة المشرف.
- مع `--install-daemon`، إذا كان وضع token يتطلب token وكان المرجع SecretRef المكوَّن لـ token غير قابل للحل، يفشل الإعداد الأولي بإغلاق آمن مع إرشادات للمعالجة.
- مع `--install-daemon`، إذا كان كل من `gateway.auth.token` و`gateway.auth.password` مكوّنين وكان `gateway.auth.mode` غير مضبوط، يمنع الإعداد الأولي التثبيت حتى يُضبط الوضع صراحةً.
- يكتب الإعداد الأولي المحلي `gateway.mode="local"` في الإعداد. وإذا كان ملف إعداد لاحق يفتقد `gateway.mode`، فاعتبر ذلك تلفًا في الإعداد أو تعديلًا يدويًا غير مكتمل، وليس اختصارًا صالحًا للوضع المحلي.
- يمثل `--allow-unconfigured` منفذ هروب منفصلًا لوقت تشغيل gateway. وهو لا يعني أن الإعداد الأولي يمكنه حذف `gateway.mode`.
مثال:
```bash
export OPENCLAW_GATEWAY_TOKEN="your-token"
openclaw onboard --non-interactive \
--mode local \
--auth-choice skip \
--gateway-auth token \
--gateway-token-ref-env OPENCLAW_GATEWAY_TOKEN \
--accept-risk
```
سلامة gateway المحلي في الوضع غير التفاعلي:
- ما لم تمرر `--skip-health`، ينتظر الإعداد الأولي وصول gateway محليًا قبل أن يخرج بنجاح.
- يبدأ `--install-daemon` أولًا مسار تثبيت gateway المُدار. ومن دونه، يجب أن يكون لديك gateway محلي يعمل بالفعل، مثل `openclaw gateway run`.
- إذا كنت تريد فقط كتابة الإعداد/مساحة العمل/تهيئة البداية ضمن الأتمتة، فاستخدم `--skip-health`.
- على Windows الأصلي، يحاول `--install-daemon` أولًا استخدام Scheduled Tasks ثم يعود إلى عنصر تسجيل دخول لكل مستخدم في مجلد Startup إذا رُفض إنشاء المهمة.
سلوك الإعداد الأولي التفاعلي مع وضع المرجع:
- اختر **Use secret reference** عندما يُطلب منك ذلك.
- ثم اختر أحد الخيارين:
- متغير بيئة
- مزود أسرار مُعد (`file` أو `exec`)
- يُجري الإعداد الأولي تحققًا تمهيديًا سريعًا قبل حفظ المرجع.
- إذا فشل التحقق، يعرض الإعداد الأولي الخطأ ويتيح لك إعادة المحاولة.
خيارات نقطة نهاية Z.AI غير التفاعلية:
ملاحظة: يقوم `--auth-choice zai-api-key` الآن بالكشف التلقائي عن أفضل نقطة نهاية Z.AI لمفتاحك (ويفضّل واجهة API العامة مع `zai/glm-5`).
وإذا كنت تريد تحديدًا نقاط نهاية GLM Coding Plan، فاختر `zai-coding-global` أو `zai-coding-cn`.
```bash
# اختيار نقطة النهاية دون مطالبة
openclaw onboard --non-interactive \
--auth-choice zai-coding-global \
--zai-api-key "$ZAI_API_KEY"
# خيارات نقاط نهاية Z.AI الأخرى:
# --auth-choice zai-coding-cn
# --auth-choice zai-global
# --auth-choice zai-cn
```
مثال Mistral غير تفاعلي:
```bash
openclaw onboard --non-interactive \
--auth-choice mistral-api-key \
--mistral-api-key "$MISTRAL_API_KEY"
```
ملاحظات التدفق:
- `quickstart`: أقل عدد من المطالبات، ويولّد gateway token تلقائيًا.
- `manual`: مطالبات كاملة للمنفذ/الربط/المصادقة (اسم بديل لـ `advanced`).
- عندما يشير خيار المصادقة إلى مزوّد مفضّل، يقوم الإعداد الأولي بتصفية
منتقيات النموذج الافتراضي وقائمة السماح مسبقًا إلى ذلك المزوّد. وبالنسبة إلى Volcengine و
BytePlus، يشمل ذلك أيضًا متغيرات coding-plan
(`volcengine-plan/*`, `byteplus-plan/*`).
- إذا لم ينتج عن مرشح المزوّد المفضّل أي نماذج محمّلة بعد، يعود الإعداد الأولي
إلى الكتالوج غير المصفّى بدلًا من ترك المنتقي فارغًا.
- في خطوة البحث على الويب، يمكن لبعض المزوّدين تشغيل
مطالبات متابعة خاصة بالمزوّد:
- يمكن لـ **Grok** تقديم إعداد `x_search` اختياري باستخدام `XAI_API_KEY`
نفسه واختيار نموذج `x_search`.
- يمكن لـ **Kimi** السؤال عن منطقة Moonshot API ‏(`api.moonshot.ai` مقابل
`api.moonshot.cn`) ونموذج البحث على الويب الافتراضي لـ Kimi.
- سلوك نطاق الرسائل المباشرة في الإعداد الأولي المحلي: [CLI Setup Reference](/start/wizard-cli-reference#outputs-and-internals).
- أسرع طريقة لأول دردشة: `openclaw dashboard` ‏(Control UI، من دون إعداد قناة).
- Custom Provider: صِل أي نقطة نهاية متوافقة مع OpenAI أو Anthropic،
بما في ذلك المزوّدين المستضافين غير المدرجين. استخدم Unknown للكشف التلقائي.
## أوامر متابعة شائعة
```bash
openclaw configure
openclaw agents add <name>
```
<Note>
لا يعني `--json` الوضع غير التفاعلي تلقائيًا. استخدم `--non-interactive` في النصوص البرمجية.
</Note>

72
docs/ar/cli/pairing.md Normal file
View File

@ -0,0 +1,72 @@
---
read_when:
- أنت تستخدم الرسائل الخاصة بوضع الاقتران وتحتاج إلى الموافقة على المرسلين
summary: مرجع CLI للأمر `openclaw pairing` ‏(approve/list لطلبات الاقتران)
title: pairing
x-i18n:
generated_at: "2026-04-05T12:39:02Z"
model: gpt-5.4
provider: openai
source_hash: 122a608ef83ec2b1011fdfd1b59b94950a4dcc8b598335b0956e2eedece4958f
source_path: cli/pairing.md
workflow: 15
---
# `openclaw pairing`
الموافقة على طلبات اقتران الرسائل الخاصة أو فحصها (للقنوات التي تدعم الاقتران).
ذو صلة:
- تدفق الاقتران: [الاقتران](/channels/pairing)
## الأوامر
```bash
openclaw pairing list telegram
openclaw pairing list --channel telegram --account work
openclaw pairing list telegram --json
openclaw pairing approve <code>
openclaw pairing approve telegram <code>
openclaw pairing approve --channel telegram --account work <code> --notify
```
## `pairing list`
عرض طلبات الاقتران المعلقة لقناة واحدة.
الخيارات:
- `[channel]`: معرّف القناة الموضعي
- `--channel <channel>`: معرّف القناة الصريح
- `--account <accountId>`: معرّف الحساب للقنوات متعددة الحسابات
- `--json`: خرج قابل للقراءة آليًا
ملاحظات:
- إذا كانت هناك عدة قنوات مكوّنة وقابلة للاقتـران، فيجب عليك توفير قناة إما موضعيًا أو باستخدام `--channel`.
- القنوات الامتدادية مسموح بها طالما أن معرّف القناة صالح.
## `pairing approve`
الموافقة على رمز اقتران معلّق والسماح لذلك المرسل.
الاستخدام:
- `openclaw pairing approve <channel> <code>`
- `openclaw pairing approve --channel <channel> <code>`
- `openclaw pairing approve <code>` عندما تكون هناك قناة واحدة فقط مكوّنة وقابلة للاقتـران
الخيارات:
- `--channel <channel>`: معرّف القناة الصريح
- `--account <accountId>`: معرّف الحساب للقنوات متعددة الحسابات
- `--notify`: إرسال تأكيد مرة أخرى إلى صاحب الطلب على القناة نفسها
## ملاحظات
- إدخال القناة: مرّره موضعيًا (`pairing list telegram`) أو باستخدام `--channel <channel>`.
- يدعم `pairing list` الخيار `--account <accountId>` للقنوات متعددة الحسابات.
- يدعم `pairing approve` الخيارين `--account <accountId>` و`--notify`.
- إذا كانت هناك قناة واحدة فقط مكوّنة وقابلة للاقتـران، فيُسمح باستخدام `pairing approve <code>`.

306
docs/ar/cli/plugins.md Normal file
View File

@ -0,0 +1,306 @@
---
read_when:
- أنت تريد تثبيت أو إدارة plugins البوابة أو الحزم المتوافقة
- أنت تريد تصحيح إخفاقات تحميل plugin
summary: مرجع CLI للأمر `openclaw plugins` (السرد، والتثبيت، وmarketplace، وإلغاء التثبيت، والتفعيل/التعطيل، وdoctor)
title: plugins
x-i18n:
generated_at: "2026-04-05T12:39:46Z"
model: gpt-5.4
provider: openai
source_hash: 8c35ccf68cd7be1af5fee175bd1ce7de88b81c625a05a23887e5780e790df925
source_path: cli/plugins.md
workflow: 15
---
# `openclaw plugins`
إدارة plugins/امتدادات البوابة، وحزم الخطافات، والحزم المتوافقة.
ذو صلة:
- نظام plugin: [Plugins](/tools/plugin)
- توافق الحزم: [حزم Plugin](/plugins/bundles)
- manifest ومخطط plugin: [manifest الـ Plugin](/plugins/manifest)
- التحصين الأمني: [الأمان](/gateway/security)
## الأوامر
```bash
openclaw plugins list
openclaw plugins list --enabled
openclaw plugins list --verbose
openclaw plugins list --json
openclaw plugins install <path-or-spec>
openclaw plugins inspect <id>
openclaw plugins inspect <id> --json
openclaw plugins inspect --all
openclaw plugins info <id>
openclaw plugins enable <id>
openclaw plugins disable <id>
openclaw plugins uninstall <id>
openclaw plugins doctor
openclaw plugins update <id>
openclaw plugins update --all
openclaw plugins marketplace list <marketplace>
openclaw plugins marketplace list <marketplace> --json
```
تأتي plugins المضمّنة مع OpenClaw. ويكون بعضها مفعّلًا افتراضيًا (على سبيل المثال
موفرو النماذج المضمّنون، وموفرو الكلام المضمّنون، وplugin المتصفح
المضمّن)؛ بينما يتطلب بعضها الآخر `plugins enable`.
يجب أن تتضمن plugins OpenClaw الأصلية ملف `openclaw.plugin.json` مع JSON
Schema مضمّن (`configSchema`، حتى لو كان فارغًا). أما الحزم المتوافقة فتستخدم manifests الحزم الخاصة بها بدلًا من ذلك.
يعرض `plugins list` القيمة `Format: openclaw` أو `Format: bundle`. كما يعرض إخراج
السرد/المعلومات المفصل أيضًا النوع الفرعي للحزمة (`codex` أو `claude` أو `cursor`) بالإضافة إلى
إمكانات الحزمة المكتشفة.
### التثبيت
```bash
openclaw plugins install <package> # ClawHub أولًا، ثم npm
openclaw plugins install clawhub:<package> # ClawHub فقط
openclaw plugins install <package> --force # الكتابة فوق التثبيت الموجود
openclaw plugins install <package> --pin # تثبيت الإصدار
openclaw plugins install <package> --dangerously-force-unsafe-install
openclaw plugins install <path> # مسار محلي
openclaw plugins install <plugin>@<marketplace> # marketplace
openclaw plugins install <plugin> --marketplace <name> # marketplace (صريح)
openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo>
```
يتم التحقق من أسماء الحزم المجردة في ClawHub أولًا، ثم npm. ملاحظة أمنية:
تعامل مع تثبيت plugins كما لو كنت تشغّل شيفرة. ويُفضَّل استخدام الإصدارات المثبتة.
إذا كان الإعداد غير صالح، فإن `plugins install` يفشل عادةً بشكل مغلق ويطلب منك
تشغيل `openclaw doctor --fix` أولًا. والاستثناء الموثق الوحيد هو مسار استرداد ضيق
لـ plugin مضمّن بالنسبة إلى plugins التي تختار صراحةً
`openclaw.install.allowInvalidConfigRecovery`.
يعيد `--force` استخدام هدف التثبيت الحالي ويكتب فوق plugin أو حزمة خطافات
مثبّتة بالفعل في مكانها. استخدمه عندما تكون تعيد عمدًا تثبيت
المعرّف نفسه من مسار محلي جديد، أو أرشيف، أو حزمة ClawHub، أو أثر npm.
ينطبق `--pin` على تثبيتات npm فقط. وهو غير مدعوم مع `--marketplace`،
لأن تثبيتات marketplace تحتفظ ببيانات وصفية عن مصدر marketplace بدلًا من
مواصفة npm.
الخيار `--dangerously-force-unsafe-install` هو خيار طوارئ للحالات الإيجابية الكاذبة
في ماسح الشيفرة الخطرة المضمّن. فهو يسمح بمتابعة التثبيت حتى
عندما يبلغ الماسح المضمّن عن نتائج `critical`، لكنه **لا** يتجاوز حظر سياسة خطاف
plugin ‏`before_install`، كما أنه **لا** يتجاوز
إخفاقات الفحص.
ينطبق هذا الخيار في CLI على تدفقات تثبيت/تحديث plugin. أما تثبيتات تبعيات
Skills المدعومة بالبوابة فتستخدم التجاوز المطابق للطلب `dangerouslyForceUnsafeInstall`، بينما يظل `openclaw skills install` تدفق تنزيل/تثبيت Skills منفصلًا عبر ClawHub.
يُعد `plugins install` أيضًا سطح التثبيت لحزم الخطافات التي تكشف
`openclaw.hooks` في `package.json`. استخدم `openclaw hooks` للحصول على رؤية
الخطافات المصفّاة والتفعيل لكل خطاف، وليس لتثبيت الحزم.
تكون مواصفات npm **خاصة بالسجل فقط** (اسم الحزمة + **إصدار دقيق** اختياري أو
**dist-tag**). ويتم رفض مواصفات Git/URL/file ونطاقات semver. كما تُشغَّل
عمليات تثبيت التبعيات باستخدام `--ignore-scripts` لأسباب تتعلق بالأمان.
تبقى المواصفات المجردة و`@latest` على المسار المستقر. وإذا قام npm بحل أيٍّ من
هذين إلى إصدار prerelease، فسيتوقف OpenClaw ويطلب منك الاشتراك صراحةً باستخدام
وسم prerelease مثل `@beta`/`@rc` أو إصدار prerelease دقيق مثل
`@1.2.3-beta.4`.
إذا طابقت مواصفة تثبيت مجردة معرّف plugin مضمّنًا (على سبيل المثال `diffs`)،
فسيقوم OpenClaw بتثبيت plugin المضمّن مباشرةً. ولتثبيت حزمة npm بالاسم
نفسه، استخدم مواصفة ذات نطاق صريح (على سبيل المثال `@scope/diffs`).
الأرشيفات المدعومة: `.zip` و`.tgz` و`.tar.gz` و`.tar`.
كما أن تثبيتات Claude marketplace مدعومة أيضًا.
تستخدم تثبيتات 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 يملك تلك الحزمة أو ذلك الإصدار:
```bash
openclaw plugins install openclaw-codex-app-server
```
يقوم OpenClaw بتنزيل أرشيف الحزمة من ClawHub، والتحقق من توافق
plugin API المُعلن / الحد الأدنى لتوافق البوابة، ثم يثبّتها عبر مسار
الأرشيف العادي. وتحتفظ التثبيتات المسجلة ببياناتها الوصفية الخاصة بمصدر ClawHub من أجل التحديثات اللاحقة.
استخدم الصيغة المختصرة `plugin@marketplace` عندما يكون اسم marketplace موجودًا في
ذاكرة السجل المحلية الخاصة بـ Claude في `~/.claude/plugins/known_marketplaces.json`:
```bash
openclaw plugins marketplace list <marketplace-name>
openclaw plugins install <plugin-name>@<marketplace-name>
```
استخدم `--marketplace` عندما تريد تمرير مصدر marketplace بشكل صريح:
```bash
openclaw plugins install <plugin-name> --marketplace <marketplace-name>
openclaw plugins install <plugin-name> --marketplace <owner/repo>
openclaw plugins install <plugin-name> --marketplace https://github.com/<owner>/<repo>
openclaw plugins install <plugin-name> --marketplace ./my-marketplace
```
يمكن أن تكون مصادر marketplace:
- اسم known-marketplace خاص بـ Claude من `~/.claude/plugins/known_marketplaces.json`
- جذر marketplace محلي أو مسار `marketplace.json`
- صيغة مختصرة لمستودع GitHub مثل `owner/repo`
- عنوان URL لمستودع GitHub مثل `https://github.com/owner/repo`
- عنوان git URL
بالنسبة إلى marketplaces البعيدة المحمّلة من GitHub أو git، يجب أن تبقى إدخالات plugin
داخل مستودع marketplace المستنسخ. ويقبل OpenClaw مصادر المسارات النسبية من
ذلك المستودع، ويرفض HTTP(S) والمسارات المطلقة وgit وGitHub وغيرها من
مصادر plugin غير المعتمدة على المسار من manifests البعيدة.
بالنسبة إلى المسارات والأرشيفات المحلية، يكتشف OpenClaw تلقائيًا:
- plugins OpenClaw الأصلية (`openclaw.plugin.json`)
- حزم متوافقة مع Codex (`.codex-plugin/plugin.json`)
- حزم متوافقة مع Claude (`.claude-plugin/plugin.json` أو تخطيط
مكونات Claude الافتراضي)
- حزم متوافقة مع Cursor (`.cursor-plugin/plugin.json`)
يتم تثبيت الحزم المتوافقة في جذر الامتدادات العادي وتشارك في التدفق نفسه الخاص
بالسرد/المعلومات/التفعيل/التعطيل. وحاليًا، فإن bundle Skills، وClaude
command-skills، وقيم `settings.json` الافتراضية الخاصة بـ Claude، وقيم Claude
الافتراضية الخاصة بـ `.lsp.json` / `lspServers` المعلنة في manifest، وCursor command-skills، وأدلة خطافات Codex المتوافقة مدعومة؛ أما إمكانات الحزم الأخرى المكتشفة فتظهر في التشخيصات/المعلومات لكنها لم تُوصَل بعد بتنفيذ وقت التشغيل.
### السرد
```bash
openclaw plugins list
openclaw plugins list --enabled
openclaw plugins list --verbose
openclaw plugins list --json
```
استخدم `--enabled` لعرض plugins المحمّلة فقط. واستخدم `--verbose` للتبديل من
عرض الجدول إلى أسطر تفاصيل لكل plugin مع بيانات
المصدر/المنشأ/الإصدار/التفعيل. واستخدم `--json` للحصول على مخزون مقروء آليًا بالإضافة إلى
تشخيصات السجل.
استخدم `--link` لتجنب نسخ دليل محلي (يضيفه إلى `plugins.load.paths`):
```bash
openclaw plugins install -l ./my-plugin
```
الخيار `--force` غير مدعوم مع `--link` لأن التثبيتات المرتبطة تعيد استخدام
المسار المصدر بدلًا من النسخ فوق هدف تثبيت مُدار.
استخدم `--pin` في تثبيتات npm لحفظ المواصفة الدقيقة المحلولة (`name@version`) في
`plugins.installs` مع إبقاء السلوك الافتراضي غير مثبت.
### إلغاء التثبيت
```bash
openclaw plugins uninstall <id>
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`.
افتراضيًا، يزيل إلغاء التثبيت أيضًا دليل تثبيت plugin الموجود تحت جذر plugins
لدليل الحالة النشط. استخدم
`--keep-files` للإبقاء على الملفات على القرص.
يُدعَم `--keep-config` كاسم مستعار مهمل لصالح `--keep-files`.
### التحديث
```bash
openclaw plugins update <id-or-npm-spec>
openclaw plugins update --all
openclaw plugins update <id-or-npm-spec> --dry-run
openclaw plugins update @openclaw/voice-call@beta
openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install
```
تنطبق التحديثات على التثبيتات المتعقبة في `plugins.installs` وعلى
تثبيتات حزم الخطافات المتعقبة في `hooks.internal.installs`.
عندما تمرر معرّف plugin، يعيد OpenClaw استخدام مواصفة التثبيت المسجلة لذلك
plugin. وهذا يعني أن dist-tags المخزنة سابقًا مثل `@beta` والإصدارات
الدقيقة المثبتة تظل مستخدمة في تشغيلات `update <id>` اللاحقة.
بالنسبة إلى تثبيتات npm، يمكنك أيضًا تمرير مواصفة صريحة لحزمة npm تتضمن dist-tag
أو إصدارًا دقيقًا. ويقوم OpenClaw بحل اسم الحزمة هذا مرة أخرى إلى سجل plugin
المتعقب، ويحدّث ذلك plugin المثبّت، ويسجل مواصفة npm الجديدة من أجل التحديثات
المستقبلية المعتمدة على المعرّف.
عند وجود قيمة hash سلامة مخزنة وتغيّر hash الأثر الذي تم جلبه،
يطبع OpenClaw تحذيرًا ويطلب التأكيد قبل المتابعة. استخدم
القيمة العامة `--yes` لتجاوز المطالبات في تشغيلات CI/غير التفاعلية.
يتوفر أيضًا `--dangerously-force-unsafe-install` في `plugins update` كتجاوز
طوارئ للحالات الإيجابية الكاذبة في فحص الشيفرة الخطرة المضمّن أثناء
تحديثات plugin. ومع ذلك، فهو لا يزال لا يتجاوز حظر سياسات `before_install` الخاصة بـ plugin
أو حظر فشل الفحص، كما أنه ينطبق فقط على تحديثات plugin وليس على تحديثات
حزم الخطافات.
### الفحص
```bash
openclaw plugins inspect <id>
openclaw plugins inspect <id> --json
```
فحص عميق لـ plugin واحد. يعرض الهوية، وحالة التحميل، والمصدر،
والإمكانات المسجلة، والخطافات، والأدوات، والأوامر، والخدمات، وطرق البوابة،
ومسارات HTTP، وأعلام السياسات، والتشخيصات، وبيانات التثبيت الوصفية، وإمكانات الحزم،
وأي دعم مكتشف لخوادم MCP أو LSP.
يتم تصنيف كل plugin بحسب ما يسجله فعليًا في وقت التشغيل:
- **plain-capability** — نوع إمكانية واحد (مثل plugin يوفّر provider فقط)
- **hybrid-capability** — أنواع إمكانيات متعددة (مثل النص + الكلام + الصور)
- **hook-only** — خطافات فقط، من دون إمكانيات أو أسطح
- **non-capability** — أدوات/أوامر/خدمات ولكن من دون إمكانيات
راجع [أشكال Plugin](/plugins/architecture#plugin-shapes) لمعرفة المزيد عن نموذج الإمكانيات.
يُخرج الخيار `--json` تقريرًا مقروءًا آليًا مناسبًا للبرمجة النصية
والتدقيق.
يعرض `inspect --all` جدولًا على مستوى الأسطول يتضمن الشكل، وأنواع
الإمكانيات، وملاحظات التوافق، وإمكانات الحزم، وأعمدة ملخص الخطافات.
`info` هو اسم مستعار لـ `inspect`.
### Doctor
```bash
openclaw plugins doctor
```
يعرض `doctor` أخطاء تحميل plugin، وتشخيصات manifest/الاكتشاف، و
ملاحظات التوافق. وعندما يكون كل شيء سليمًا فإنه يطبع `No plugin issues
detected.`
### Marketplace
```bash
openclaw plugins marketplace list <source>
openclaw plugins marketplace list <source> --json
```
يقبل أمر marketplace list مسار marketplace محلي، أو مسار `marketplace.json`، أو
صيغة GitHub المختصرة مثل `owner/repo`، أو عنوان URL لمستودع GitHub، أو عنوان git URL. ويقوم `--json`
بطباعة تسمية المصدر المحلولة بالإضافة إلى manifest الـ marketplace المحلّل
وإدخالات plugin.

59
docs/ar/cli/qr.md Normal file
View File

@ -0,0 +1,59 @@
---
read_when:
- تريد إقران تطبيق عقدة محمول ببوابة بسرعة
- تحتاج إلى إخراج رمز إعداد للمشاركة عن بُعد أو يدويًا
summary: مرجع CLI للأمر `openclaw qr` (إنشاء QR لإقران الهاتف المحمول + رمز الإعداد)
title: qr
x-i18n:
generated_at: "2026-04-05T12:39:11Z"
model: gpt-5.4
provider: openai
source_hash: ee6469334ad09037318f938c7ac609b7d5e3385c0988562501bb02a1bfa411ff
source_path: cli/qr.md
workflow: 15
---
# `openclaw qr`
أنشئ QR لإقران الهاتف المحمول ورمز إعداد من تكوين البوابة الحالي لديك.
## الاستخدام
```bash
openclaw qr
openclaw qr --setup-code-only
openclaw qr --json
openclaw qr --remote
openclaw qr --url wss://gateway.example/ws
```
## الخيارات
- `--remote`: يفضّل `gateway.remote.url`؛ وإذا لم يكن مضبوطًا، فلا يزال بإمكان `gateway.tailscale.mode=serve|funnel` توفير URL العام البعيد
- `--url <url>`: تجاوز URL البوابة المستخدم في الحمولة
- `--public-url <url>`: تجاوز URL العام المستخدم في الحمولة
- `--token <token>`: تجاوز token البوابة الذي يتولى تدفق bootstrap المصادقة مقابله
- `--password <password>`: تجاوز كلمة مرور البوابة التي يتولى تدفق bootstrap المصادقة مقابلها
- `--setup-code-only`: طباعة رمز الإعداد فقط
- `--no-ascii`: تخطي عرض QR بصيغة ASCII
- `--json`: إخراج JSON (`setupCode`, `gatewayUrl`, `auth`, `urlSource`)
## ملاحظات
- `--token` و`--password` متنافيان.
- يحمل رمز الإعداد نفسه الآن `bootstrapToken` قصير العمر ومعتمًا، وليس token/كلمة مرور البوابة المشتركة.
- في تدفق bootstrap المضمّن للعقدة/المشغّل، يظل token العقدة الأساسي يُمنح مع `scopes: []`.
- إذا أصدر bootstrap handoff أيضًا operator token، فإنه يبقى محصورًا في allowlist الخاصة بالـ bootstrap: ‏`operator.approvals` و`operator.read` و`operator.talk.secrets` و`operator.write`.
- تكون فحوصات نطاق bootstrap مسبوقة بالدور. وتلبّي allowlist الخاصة بالمشغّل طلبات المشغّل فقط؛ أما الأدوار غير المشغّلة فما زالت تحتاج إلى scopes تحت بادئة دورها الخاصة.
- يفشل إقران الهاتف المحمول بشكل fail-closed مع URLات بوابة Tailscale/العامة من نوع `ws://`. وما زال `ws://` على شبكات LAN الخاصة مدعومًا، لكن يجب أن تستخدم مسارات الهاتف المحمول عبر Tailscale/العامة Tailscale Serve/Funnel أو URL بوابة من نوع `wss://`.
- مع `--remote`، يتطلب OpenClaw إما `gateway.remote.url` أو
`gateway.tailscale.mode=serve|funnel`.
- مع `--remote`، إذا كانت بيانات الاعتماد البعيدة النشطة فعليًا مكوّنة كـ SecretRefs ولم تمرر `--token` أو `--password`، فسيقوم الأمر بحلها من snapshot البوابة النشط. وإذا كانت البوابة غير متاحة، يفشل الأمر سريعًا.
- من دون `--remote`، يتم حل SecretRefs الخاصة بمصادقة البوابة المحلية عندما لا يتم تمرير تجاوز مصادقة عبر CLI:
- يتم حل `gateway.auth.token` عندما يمكن لمصادقة token أن تفوز (وجود `gateway.auth.mode="token"` صريح أو وضع مستنتج حيث لا يفوز أي مصدر كلمة مرور).
- يتم حل `gateway.auth.password` عندما يمكن لمصادقة كلمة المرور أن تفوز (وجود `gateway.auth.mode="password"` صريح أو وضع مستنتج من دون token فائز من auth/env).
- إذا كان كل من `gateway.auth.token` و`gateway.auth.password` مكوّنين (بما في ذلك SecretRefs) ولم يتم ضبط `gateway.auth.mode`، فإن حل رمز الإعداد يفشل حتى يتم ضبط الوضع صراحةً.
- ملاحظة حول اختلاف إصدار البوابة: يتطلب مسار هذا الأمر بوابة تدعم `secrets.resolve`؛ وتُرجع البوابات الأقدم خطأ unknown-method.
- بعد المسح، وافق على إقران الجهاز باستخدام:
- `openclaw devices list`
- `openclaw devices approve <requestId>`

42
docs/ar/cli/reset.md Normal file
View File

@ -0,0 +1,42 @@
---
read_when:
- تريد مسح الحالة المحلية مع الإبقاء على CLI مثبتًا
- تريد تنفيذًا تجريبيًا لما سيتم حذفه
summary: مرجع CLI للأمر `openclaw reset` (إعادة تعيين الحالة/التهيئة المحلية)
title: reset
x-i18n:
generated_at: "2026-04-05T12:39:04Z"
model: gpt-5.4
provider: openai
source_hash: ad464700f948bebe741ec309f25150714f0b280834084d4f531327418a42c79b
source_path: cli/reset.md
workflow: 15
---
# `openclaw reset`
إعادة تعيين التهيئة/الحالة المحلية (مع الإبقاء على CLI مثبتًا).
الخيارات:
- `--scope <scope>`: ‏`config` أو `config+creds+sessions` أو `full`
- `--yes`: تخطي مطالبات التأكيد
- `--non-interactive`: تعطيل المطالبات؛ ويتطلب `--scope` و`--yes`
- `--dry-run`: طباعة الإجراءات من دون إزالة الملفات
أمثلة:
```bash
openclaw backup create
openclaw reset
openclaw reset --dry-run
openclaw reset --scope config --yes --non-interactive
openclaw reset --scope config+creds+sessions --yes --non-interactive
openclaw reset --scope full --yes --non-interactive
```
ملاحظات:
- شغّل `openclaw backup create` أولًا إذا كنت تريد لقطة قابلة للاستعادة قبل إزالة الحالة المحلية.
- إذا حذفت `--scope`، فسيستخدم `openclaw reset` مطالبة تفاعلية لاختيار ما يجب إزالته.
- لا يكون `--non-interactive` صالحًا إلا عند ضبط كل من `--scope` و`--yes`.

204
docs/ar/cli/sandbox.md Normal file
View File

@ -0,0 +1,204 @@
---
read_when: You are managing sandbox runtimes or debugging sandbox/tool-policy behavior.
status: active
summary: إدارة بيئات تشغيل sandbox وفحص سياسة sandbox الفعالة
title: Sandbox CLI
x-i18n:
generated_at: "2026-04-05T12:39:24Z"
model: gpt-5.4
provider: openai
source_hash: fa2783037da2901316108d35e04bb319d5d57963c2764b9146786b3c6474b48a
source_path: cli/sandbox.md
workflow: 15
---
# Sandbox CLI
إدارة بيئات تشغيل sandbox لتنفيذ الوكلاء المعزول.
## نظرة عامة
يمكن لـ OpenClaw تشغيل الوكلاء داخل بيئات تشغيل sandbox معزولة لأسباب أمنية. تساعدك أوامر `sandbox` على فحص تلك البيئات وإعادة إنشائها بعد التحديثات أو تغييرات الإعدادات.
يعني ذلك اليوم عادةً:
- حاويات Docker sandbox
- بيئات تشغيل SSH sandbox عندما يكون `agents.defaults.sandbox.backend = "ssh"`
- بيئات تشغيل OpenShell sandbox عندما يكون `agents.defaults.sandbox.backend = "openshell"`
بالنسبة إلى `ssh` وOpenShell `remote`، تكون إعادة الإنشاء أكثر أهمية من Docker:
- تكون مساحة العمل البعيدة هي المرجع الأساسي بعد التهيئة الأولى
- يحذف `openclaw sandbox recreate` مساحة العمل البعيدة المرجعية تلك للنطاق المحدد
- وتقوم أول عملية استخدام لاحقة بتهيئتها مرة أخرى من مساحة العمل المحلية الحالية
## الأوامر
### `openclaw sandbox explain`
افحص وضع/nطاق/وصول مساحة العمل الفعّال في **sandbox**، وسياسة أداة sandbox، وبوابات الرفع، مع مسارات مفاتيح الإعدادات اللازمة للإصلاح.
```bash
openclaw sandbox explain
openclaw sandbox explain --session agent:main:main
openclaw sandbox explain --agent work
openclaw sandbox explain --json
```
### `openclaw sandbox list`
اعرض جميع بيئات تشغيل sandbox مع حالتها وإعداداتها.
```bash
openclaw sandbox list
openclaw sandbox list --browser # List only browser containers
openclaw sandbox list --json # JSON output
```
**يتضمن الخرج:**
- اسم بيئة التشغيل وحالتها
- الخلفية (`docker` أو `openshell` أو غيرها)
- تسمية الإعدادات وما إذا كانت تطابق الإعدادات الحالية
- العمر (الوقت منذ الإنشاء)
- وقت الخمول (الوقت منذ آخر استخدام)
- الجلسة/الوكيل المرتبط
### `openclaw sandbox recreate`
أزل بيئات تشغيل sandbox لفرض إعادة إنشائها باستخدام الإعدادات المحدّثة.
```bash
openclaw sandbox recreate --all # Recreate all containers
openclaw sandbox recreate --session main # Specific session
openclaw sandbox recreate --agent mybot # Specific agent
openclaw sandbox recreate --browser # Only browser containers
openclaw sandbox recreate --all --force # Skip confirmation
```
**الخيارات:**
- `--all`: إعادة إنشاء جميع حاويات sandbox
- `--session <key>`: إعادة إنشاء الحاوية لجلسة محددة
- `--agent <id>`: إعادة إنشاء الحاويات لوكيل محدد
- `--browser`: إعادة إنشاء حاويات المتصفح فقط
- `--force`: تخطي مطالبة التأكيد
**مهم:** تتم إعادة إنشاء بيئات التشغيل تلقائيًا عند استخدام الوكيل في المرة التالية.
## حالات الاستخدام
### بعد تحديث صورة Docker
```bash
# Pull new image
docker pull openclaw-sandbox:latest
docker tag openclaw-sandbox:latest openclaw-sandbox:bookworm-slim
# Update config to use new image
# Edit config: agents.defaults.sandbox.docker.image (or agents.list[].sandbox.docker.image)
# Recreate containers
openclaw sandbox recreate --all
```
### بعد تغيير إعدادات sandbox
```bash
# Edit config: agents.defaults.sandbox.* (or agents.list[].sandbox.*)
# Recreate to apply new config
openclaw sandbox recreate --all
```
### بعد تغيير هدف SSH أو مواد مصادقة SSH
```bash
# Edit config:
# - agents.defaults.sandbox.backend
# - agents.defaults.sandbox.ssh.target
# - agents.defaults.sandbox.ssh.workspaceRoot
# - agents.defaults.sandbox.ssh.identityFile / certificateFile / knownHostsFile
# - agents.defaults.sandbox.ssh.identityData / certificateData / knownHostsData
openclaw sandbox recreate --all
```
بالنسبة إلى الخلفية الأساسية `ssh`، فإن إعادة الإنشاء تحذف جذر مساحة العمل البعيد لكل نطاق
على هدف SSH. وتقوم أول عملية تشغيل لاحقة بتهيئته مرة أخرى من مساحة العمل المحلية.
### بعد تغيير مصدر OpenShell أو السياسة أو الوضع
```bash
# Edit config:
# - agents.defaults.sandbox.backend
# - plugins.entries.openshell.config.from
# - plugins.entries.openshell.config.mode
# - plugins.entries.openshell.config.policy
openclaw sandbox recreate --all
```
بالنسبة إلى وضع OpenShell `remote`، فإن إعادة الإنشاء تحذف مساحة العمل البعيدة المرجعية
لذلك النطاق. وتقوم أول عملية تشغيل لاحقة بتهيئتها مرة أخرى من مساحة العمل المحلية.
### بعد تغيير setupCommand
```bash
openclaw sandbox recreate --all
# or just one agent:
openclaw sandbox recreate --agent family
```
### لوكيل محدد فقط
```bash
# Update only one agent's containers
openclaw sandbox recreate --agent alfred
```
## لماذا يلزم ذلك؟
**المشكلة:** عندما تحدّث إعدادات sandbox:
- تستمر بيئات التشغيل الموجودة في العمل بالإعدادات القديمة
- لا يتم تقليم بيئات التشغيل إلا بعد 24 ساعة من عدم النشاط
- تبقي الوكلاء الذين يُستخدمون بانتظام بيئات التشغيل القديمة حيّة إلى أجل غير مسمى
**الحل:** استخدم `openclaw sandbox recreate` لفرض إزالة بيئات التشغيل القديمة. وستُعاد إنشاؤها تلقائيًا بالإعدادات الحالية عند الحاجة إليها لاحقًا.
نصيحة: فضّل `openclaw sandbox recreate` على التنظيف اليدوي الخاص بكل خلفية.
فهو يستخدم سجل بيئات تشغيل Gateway ويتجنب حالات عدم التطابق عند تغيّر مفاتيح النطاق/الجلسة.
## الإعدادات
توجد إعدادات Sandbox في `~/.openclaw/openclaw.json` ضمن `agents.defaults.sandbox` (وتوضع التجاوزات لكل وكيل في `agents.list[].sandbox`):
```jsonc
{
"agents": {
"defaults": {
"sandbox": {
"mode": "all", // off, non-main, all
"backend": "docker", // docker, ssh, openshell
"scope": "agent", // session, agent, shared
"docker": {
"image": "openclaw-sandbox:bookworm-slim",
"containerPrefix": "openclaw-sbx-",
// ... more Docker options
},
"prune": {
"idleHours": 24, // Auto-prune after 24h idle
"maxAgeDays": 7, // Auto-prune after 7 days
},
},
},
},
}
```
## راجع أيضًا
- [توثيق Sandbox](/gateway/sandboxing)
- [إعداد الوكيل](/concepts/agent-workspace)
- [أمر Doctor](/gateway/doctor) - التحقق من إعداد sandbox

204
docs/ar/cli/secrets.md Normal file
View File

@ -0,0 +1,204 @@
---
read_when:
- إعادة حل مراجع الأسرار في وقت التشغيل
- تدقيق بقايا النص الصريح والمراجع غير المحلولة
- تكوين SecretRefs وتطبيق تغييرات تنظيف أحادية الاتجاه
summary: مرجع CLI للأمر `openclaw secrets` ‏(reload وaudit وconfigure وapply)
title: secrets
x-i18n:
generated_at: "2026-04-05T12:39:30Z"
model: gpt-5.4
provider: openai
source_hash: f436ba089d752edb766c0a3ce746ee6bca1097b22c9b30e3d9715cb0bb50bf47
source_path: cli/secrets.md
workflow: 15
---
# `openclaw secrets`
استخدم `openclaw secrets` لإدارة SecretRefs والحفاظ على سلامة لقطة وقت التشغيل النشطة.
أدوار الأوامر:
- `reload`: ‏Gateway RPC ‏(`secrets.reload`) الذي يعيد حل المراجع ويبدّل لقطة وقت التشغيل فقط عند النجاح الكامل (من دون كتابة أي تكوين).
- `audit`: فحص للقراءة فقط للتكوين/المصادقة/مخازن النماذج المُولدة وبقايا الأنظمة القديمة بحثًا عن النص الصريح، والمراجع غير المحلولة، وانحراف الأولوية (يتم تخطي مراجع exec ما لم يتم تعيين `--allow-exec`).
- `configure`: مخطط تفاعلي لإعداد المزوّد، وربط الأهداف، والفحص المسبق (يتطلب TTY).
- `apply`: تنفيذ خطة محفوظة (`--dry-run` للتحقق فقط؛ يتخطى التشغيل الجاف فحوصات exec افتراضيًا، بينما يرفض وضع الكتابة الخطط التي تحتوي على exec ما لم يتم تعيين `--allow-exec`)، ثم تنظيف بقايا النص الصريح المستهدفة.
حلقة التشغيل الموصى بها:
```bash
openclaw secrets audit --check
openclaw secrets configure
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json
openclaw secrets audit --check
openclaw secrets reload
```
إذا كانت خطتك تتضمن `exec` SecretRefs/providers، فمرّر `--allow-exec` في كل من أوامر التشغيل الجاف وأوامر التطبيق في وضع الكتابة.
ملاحظة حول رمز الخروج في CI/البوابات:
- يعيد `audit --check` القيمة `1` عند وجود نتائج.
- تعيد المراجع غير المحلولة القيمة `2`.
ذو صلة:
- دليل الأسرار: [إدارة الأسرار](/gateway/secrets)
- سطح بيانات الاعتماد: [سطح بيانات اعتماد SecretRef](/reference/secretref-credential-surface)
- دليل الأمان: [الأمان](/gateway/security)
## إعادة تحميل لقطة وقت التشغيل
إعادة حل مراجع الأسرار وتبديل لقطة وقت التشغيل بشكل ذري.
```bash
openclaw secrets reload
openclaw secrets reload --json
openclaw secrets reload --url ws://127.0.0.1:18789 --token <token>
```
ملاحظات:
- يستخدم طريقة Gateway RPC المسماة `secrets.reload`.
- إذا فشل الحل، يحتفظ gateway بآخر لقطة سليمة معروفة ويعيد خطأً (من دون تفعيل جزئي).
- يتضمن رد JSON الحقل `warningCount`.
الخيارات:
- `--url <url>`
- `--token <token>`
- `--timeout <ms>`
- `--json`
## التدقيق
فحص حالة OpenClaw بحثًا عن:
- تخزين الأسرار بنص صريح
- المراجع غير المحلولة
- انحراف الأولوية (حيث تقوم بيانات اعتماد `auth-profiles.json` بحجب مراجع `openclaw.json`)
- بقايا `agents/*/agent/models.json` المُولدة (قيم `apiKey` الخاصة بالمزوّد والرؤوس الحساسة الخاصة بالمزوّد)
- بقايا الأنظمة القديمة (إدخالات مخزن المصادقة القديم، وتذكيرات OAuth)
ملاحظة بقايا الرؤوس:
- يعتمد اكتشاف الرؤوس الحساسة الخاصة بالمزوّد على الاستدلال بالاسم (أسماء رؤوس المصادقة/بيانات الاعتماد الشائعة والأجزاء مثل `authorization` و`x-api-key` و`token` و`secret` و`password` و`credential`).
```bash
openclaw secrets audit
openclaw secrets audit --check
openclaw secrets audit --json
openclaw secrets audit --allow-exec
```
سلوك الخروج:
- يُنهي `--check` التنفيذ بقيمة غير صفرية عند وجود نتائج.
- تُنهي المراجع غير المحلولة التنفيذ برمز غير صفري ذي أولوية أعلى.
أبرز معالم شكل التقرير:
- `status`: ‏`clean | findings | unresolved`
- `resolution`: ‏`refsChecked` و`skippedExecRefs` و`resolvabilityComplete`
- `summary`: ‏`plaintextCount` و`unresolvedRefCount` و`shadowedRefCount` و`legacyResidueCount`
- رموز النتائج:
- `PLAINTEXT_FOUND`
- `REF_UNRESOLVED`
- `REF_SHADOWED`
- `LEGACY_RESIDUE`
## التكوين (مساعد تفاعلي)
أنشئ تغييرات المزوّد وSecretRef بشكل تفاعلي، وشغّل الفحص المسبق، وطبّقها اختياريًا:
```bash
openclaw secrets configure
openclaw secrets configure --plan-out /tmp/openclaw-secrets-plan.json
openclaw secrets configure --apply --yes
openclaw secrets configure --providers-only
openclaw secrets configure --skip-provider-setup
openclaw secrets configure --agent ops
openclaw secrets configure --json
```
التدفق:
- إعداد المزوّد أولًا (`add/edit/remove` لأسماء `secrets.providers` المستعارة).
- ربط بيانات الاعتماد ثانيًا (تحديد الحقول وتعيين مراجع `{source, provider, id}`).
- الفحص المسبق والتطبيق الاختياري أخيرًا.
العلامات:
- `--providers-only`: تكوين `secrets.providers` فقط، وتخطي ربط بيانات الاعتماد.
- `--skip-provider-setup`: تخطي إعداد المزوّد وربط بيانات الاعتماد بالمزوّدين الحاليين.
- `--agent <id>`: قصر اكتشاف الأهداف والكتابات في `auth-profiles.json` على مخزن وكيل واحد.
- `--allow-exec`: السماح بفحوصات exec SecretRef أثناء الفحص المسبق/التطبيق (قد يؤدي إلى تنفيذ أوامر المزوّد).
ملاحظات:
- يتطلب TTY تفاعليًا.
- لا يمكنك الجمع بين `--providers-only` و`--skip-provider-setup`.
- يستهدف `configure` الحقول الحاملة للأسرار في `openclaw.json` بالإضافة إلى `auth-profiles.json` ضمن نطاق الوكيل المحدد.
- يدعم `configure` إنشاء تعيينات جديدة في `auth-profiles.json` مباشرة داخل تدفق الاختيار.
- السطح المدعوم المعتمد: [سطح بيانات اعتماد SecretRef](/reference/secretref-credential-surface).
- ينفذ حلًا مسبقًا قبل التطبيق.
- إذا كان الفحص المسبق/التطبيق يتضمن مراجع exec، فأبقِ `--allow-exec` مضبوطًا في كلتا الخطوتين.
- تفعل الخطط المُولدة افتراضيًا خيارات التنظيف (`scrubEnv` و`scrubAuthProfilesForProviderTargets` و`scrubLegacyAuthJson` كلها مفعلة).
- مسار التطبيق أحادي الاتجاه للقيم النصية الصريحة التي تم تنظيفها.
- من دون `--apply`، سيظل CLI يطالبك بالسؤال `Apply this plan now?` بعد الفحص المسبق.
- مع `--apply` (ومن دون `--yes`)، يطلب CLI تأكيدًا إضافيًا غير قابل للتراجع.
- يطبع `--json` الخطة + تقرير الفحص المسبق، لكن الأمر يظل يتطلب TTY تفاعليًا.
ملاحظة أمان مزوّد exec:
- غالبًا ما تعرض تثبيتات Homebrew ملفات تنفيذية مرتبطة رمزيًا ضمن `/opt/homebrew/bin/*`.
- عيّن `allowSymlinkCommand: true` فقط عند الحاجة إلى مسارات موثوقة يديرها مدير الحزم، وأقرنه مع `trustedDirs` (مثل `["/opt/homebrew"]`).
- في Windows، إذا لم يكن تحقق ACL متاحًا لمسار مزوّد ما، فإن OpenClaw يفشل بشكل مغلق. للمسارات الموثوقة فقط، عيّن `allowInsecurePath: true` على ذلك المزوّد لتجاوز فحوصات أمان المسار.
## تطبيق خطة محفوظة
طبّق أو نفّذ فحصًا مسبقًا لخطة مُولدة سابقًا:
```bash
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --allow-exec
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run --allow-exec
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --json
```
سلوك exec:
- يتحقق `--dry-run` من الفحص المسبق من دون كتابة ملفات.
- يتم تخطي فحوصات exec SecretRef افتراضيًا في التشغيل الجاف.
- يرفض وضع الكتابة الخطط التي تحتوي على exec SecretRefs/providers ما لم يتم تعيين `--allow-exec`.
- استخدم `--allow-exec` للاشتراك في فحوصات/تنفيذ مزوّد exec في أي من الوضعين.
تفاصيل عقد الخطة (مسارات الأهداف المسموح بها، وقواعد التحقق، ودلالات الفشل):
- [عقد خطة تطبيق الأسرار](/gateway/secrets-plan-contract)
ما الذي قد يحدّثه `apply`:
- `openclaw.json` ‏(أهداف SecretRef + عمليات upsert/delete للمزوّد)
- `auth-profiles.json` ‏(تنظيف أهداف المزوّد)
- بقايا `auth.json` القديمة
- مفاتيح الأسرار المعروفة في `~/.openclaw/.env` التي تم ترحيل قيمها
## لماذا لا توجد نسخ احتياطية للتراجع
لا يقوم `secrets apply` عمدًا بكتابة نسخ احتياطية للتراجع تحتوي على قيم النص الصريح القديمة.
تأتي السلامة من فحص مسبق صارم + تطبيق شبه ذري مع استعادة داخل الذاكرة بأفضل جهد عند الفشل.
## مثال
```bash
openclaw secrets audit --check
openclaw secrets configure
openclaw secrets audit --check
```
إذا استمر `audit --check` في الإبلاغ عن نتائج نص صريح، فحدّث مسارات الأهداف المتبقية التي تم الإبلاغ عنها وأعد تشغيل التدقيق.

93
docs/ar/cli/security.md Normal file
View File

@ -0,0 +1,93 @@
---
read_when:
- تريد تشغيل تدقيق أمني سريع على التهيئة/الحالة
- تريد تطبيق اقتراحات “fix” الآمنة (الأذونات، وتشديد الإعدادات الافتراضية)
summary: مرجع CLI للأمر `openclaw security` (تدقيق مشكلات الأمان الشائعة وإصلاحها)
title: security
x-i18n:
generated_at: "2026-04-05T12:39:26Z"
model: gpt-5.4
provider: openai
source_hash: e5a3e4ab8e0dfb6c10763097cb4483be2431985f16de877523eb53e2122239ae
source_path: cli/security.md
workflow: 15
---
# `openclaw security`
أدوات الأمان (تدقيق + إصلاحات اختيارية).
ذو صلة:
- دليل الأمان: [الأمان](/gateway/security)
## التدقيق
```bash
openclaw security audit
openclaw security audit --deep
openclaw security audit --deep --password <password>
openclaw security audit --deep --token <token>
openclaw security audit --fix
openclaw security audit --json
```
يحذر التدقيق عندما يتشارك عدة مرسلين للرسائل المباشرة الجلسة الرئيسية، ويوصي باستخدام **وضع الرسائل المباشرة الآمن**: ‏`session.dmScope="per-channel-peer"` (أو `per-account-channel-peer` للقنوات متعددة الحسابات) لصناديق الوارد المشتركة.
وهذا مخصص لتقوية صناديق الوارد التعاونية/المشتركة. ولا يُعد Gateway واحد مشترك بين مشغلين غير موثوقين/عدائيين إعدادًا موصى به؛ افصل حدود الثقة باستخدام Gateways منفصلة (أو مستخدمي/مضيفي نظام تشغيل منفصلين).
كما أنه يصدر `security.trust_model.multi_user_heuristic` عندما توحي التهيئة بوجود إدخال محتمل لمستخدمين مشتركين (على سبيل المثال سياسة رسائل مباشرة/مجموعات مفتوحة، أو أهداف مجموعات مهيأة، أو قواعد مرسلين عامة)، ويذكرك بأن OpenClaw يعتمد افتراضيًا نموذج ثقة المساعد الشخصي.
وبالنسبة إلى الإعدادات المقصودة للمستخدمين المشتركين، فإن إرشادات التدقيق هي وضع جميع الجلسات في sandbox، والإبقاء على وصول نظام الملفات ضمن نطاق workspace، وإبقاء الهويات أو بيانات الاعتماد الشخصية/الخاصة خارج وقت التشغيل هذا.
كما يحذر أيضًا عند استخدام نماذج صغيرة (`<=300B`) من دون sandbox ومع تمكين أدوات الويب/المتصفح.
وبالنسبة إلى إدخال webhook، فإنه يحذر عندما يعيد `hooks.token` استخدام token الخاص بـ Gateway، أو عندما يكون `hooks.token` قصيرًا، أو عندما تكون `hooks.path="/"`، أو عندما لا تكون `hooks.defaultSessionKey` مضبوطة، أو عندما تكون `hooks.allowedAgentIds` غير مقيّدة، أو عندما تكون تجاوزات `sessionKey` للطلبات مفعّلة، أو عندما تكون التجاوزات مفعلة من دون `hooks.allowedSessionKeyPrefixes`.
كما يحذر أيضًا عند تهيئة إعدادات sandbox Docker بينما وضع sandbox معطّل، وعندما يستخدم `gateway.nodes.denyCommands` إدخالات غير فعالة شبيهة بالأنماط/غير معروفة (مطابقة دقيقة لاسم أمر العقدة فقط، وليس تصفية نص shell)، وعندما يفعّل `gateway.nodes.allowCommands` صراحة أوامر عقدة خطيرة، وعندما يتم تجاوز `tools.profile="minimal"` العام بواسطة ملفات تعريف أدوات الوكيل، وعندما تكشف المجموعات المفتوحة أدوات وقت التشغيل/نظام الملفات من دون حواجز sandbox/workspace، وعندما يمكن الوصول إلى أدوات extension plugin المثبتة في ظل سياسة أدوات متساهلة.
كما يشير أيضًا إلى `gateway.allowRealIpFallback=true` (خطر انتحال الترويسات إذا أسيء ضبط الوكلاء) و`discovery.mdns.mode="full"` (تسرّب البيانات الوصفية عبر سجلات mDNS TXT).
كما يحذر أيضًا عندما يستخدم متصفح sandbox شبكة Docker من نوع `bridge` من دون `sandbox.browser.cdpSourceRange`.
كما يشير أيضًا إلى أوضاع شبكة sandbox Docker الخطيرة (بما في ذلك انضمامات مساحة الأسماء `host` و`container:*`).
كما يحذر أيضًا عندما تكون حاويات Docker الحالية لمتصفح sandbox تحتوي على تسميات hash مفقودة/قديمة (على سبيل المثال الحاويات السابقة للترحيل التي تفتقد `openclaw.browserConfigEpoch`) ويوصي باستخدام `openclaw sandbox recreate --browser --all`.
كما يحذر أيضًا عندما تكون سجلات تثبيت plugin/hook المعتمدة على npm غير مثبّتة بإصدار محدد، أو تفتقد بيانات integrity الوصفية، أو تنحرف عن إصدارات الحزم المثبتة حاليًا.
كما يحذر عندما تعتمد قوائم السماح الخاصة بالقنوات على أسماء/بريد إلكتروني/وسوم قابلة للتغيير بدلًا من معرّفات ثابتة (Discord وSlack وGoogle Chat وMicrosoft Teams وMattermost ونطاقات IRC عند الاقتضاء).
كما يحذر عندما يترك `gateway.auth.mode="none"` واجهات Gateway HTTP API قابلة للوصول من دون سر مشترك (`/tools/invoke` بالإضافة إلى أي نقطة نهاية `/v1/*` مفعّلة).
وتُعد الإعدادات التي تبدأ بـ `dangerous`/`dangerously` تجاوزات صريحة من المشغل لكسر الزجاج عند الطوارئ؛ ولا يُعد تمكين أحدها، بحد ذاته، تقرير ثغرة أمنية.
للحصول على الجرد الكامل للمعلمات الخطيرة، راجع قسم "ملخص العلامات غير الآمنة أو الخطيرة" في [الأمان](/gateway/security).
سلوك SecretRef:
- يقوم `security audit` بحل SecretRefs المدعومة في وضع القراءة فقط للمسارات المستهدفة الخاصة به.
- إذا كان SecretRef غير متاح في مسار الأمر الحالي، يستمر التدقيق ويبلّغ عن `secretDiagnostics` (بدلًا من التعطل).
- لا يؤدي `--token` و`--password` إلا إلى تجاوز مصادقة deep-probe لهذا الاستدعاء من الأمر؛ وهما لا يعيدان كتابة التهيئة أو تعيينات SecretRef.
## إخراج JSON
استخدم `--json` لفحوصات CI/السياسات:
```bash
openclaw security audit --json | jq '.summary'
openclaw security audit --deep --json | jq '.findings[] | select(.severity=="critical") | .checkId'
```
إذا جرى دمج `--fix` و`--json`، فسيتضمن الإخراج إجراءات الإصلاح والتقرير النهائي معًا:
```bash
openclaw security audit --fix --json | jq '{fix: .fix.ok, summary: .report.summary}'
```
## ما الذي يغيره `--fix`
يطبق `--fix` معالجات آمنة وحتمية:
- يحول القيم الشائعة `groupPolicy="open"` إلى `groupPolicy="allowlist"` (بما في ذلك متغيرات الحسابات في القنوات المدعومة)
- عندما تتحول سياسة مجموعة WhatsApp إلى `allowlist`، فإنه يزرع `groupAllowFrom` من
ملف `allowFrom` المخزن عندما تكون تلك القائمة موجودة ولا تكون التهيئة قد عرّفت بالفعل
`allowFrom`
- يضبط `logging.redactSensitive` من `"off"` إلى `"tools"`
- يشدد الأذونات للحالة/التهيئة والملفات الحساسة الشائعة
(`credentials/*.json` و`auth-profiles.json` و`sessions.json` وملفات الجلسات
`*.jsonl`)
- كما يشدد أيضًا ملفات تضمين التهيئة المشار إليها من `openclaw.json`
- يستخدم `chmod` على مضيفات POSIX وعمليات إعادة تعيين `icacls` على Windows
لا يقوم `--fix` بما يلي:
- تدوير tokens أو كلمات المرور أو مفاتيح API
- تعطيل الأدوات (`gateway` أو `cron` أو `exec` وما إلى ذلك)
- تغيير خيارات ربط/auth/تعرض الشبكة الخاصة بـ gateway
- إزالة أو إعادة كتابة plugins/Skills

120
docs/ar/cli/sessions.md Normal file
View File

@ -0,0 +1,120 @@
---
read_when:
- تريد عرض الجلسات المخزنة ورؤية النشاط الأخير
summary: مرجع CLI للأمر `openclaw sessions` (عرض الجلسات المخزنة + الاستخدام)
title: sessions
x-i18n:
generated_at: "2026-04-05T12:39:25Z"
model: gpt-5.4
provider: openai
source_hash: 47eb55d90bd0681676283310cfa50dcacc95dff7d9a39bf2bb188788c6e5e5ba
source_path: cli/sessions.md
workflow: 15
---
# `openclaw sessions`
اعرض جلسات المحادثة المخزنة.
```bash
openclaw sessions
openclaw sessions --agent work
openclaw sessions --all-agents
openclaw sessions --active 120
openclaw sessions --verbose
openclaw sessions --json
```
اختيار النطاق:
- الافتراضي: مخزن الوكيل الافتراضي المكوَّن
- `--verbose`: تسجيل verbose
- `--agent <id>`: مخزن وكيل مكوَّن واحد
- `--all-agents`: تجميع جميع مخازن الوكلاء المكوَّنة
- `--store <path>`: مسار مخزن صريح (لا يمكن دمجه مع `--agent` أو `--all-agents`)
يقرأ `openclaw sessions --all-agents` مخازن الوكلاء المكوَّنة. ويكون اكتشاف
جلسات Gateway وACP أوسع: إذ يشمل أيضًا المخازن الموجودة على القرص فقط التي
يتم العثور عليها ضمن الجذر الافتراضي `agents/` أو جذر `session.store`
المعتمد على قالب. ويجب أن تُحل هذه المخازن المكتشفة إلى ملفات `sessions.json`
عادية داخل جذر الوكيل؛ ويتم تخطي الروابط الرمزية والمسارات الخارجة عن الجذر.
أمثلة JSON:
`openclaw sessions --all-agents --json`:
```json
{
"path": null,
"stores": [
{ "agentId": "main", "path": "/home/user/.openclaw/agents/main/sessions/sessions.json" },
{ "agentId": "work", "path": "/home/user/.openclaw/agents/work/sessions/sessions.json" }
],
"allAgents": true,
"count": 2,
"activeMinutes": null,
"sessions": [
{ "agentId": "main", "key": "agent:main:main", "model": "gpt-5" },
{ "agentId": "work", "key": "agent:work:main", "model": "claude-opus-4-6" }
]
}
```
## صيانة التنظيف
شغّل الصيانة الآن (بدلًا من انتظار دورة الكتابة التالية):
```bash
openclaw sessions cleanup --dry-run
openclaw sessions cleanup --agent work --dry-run
openclaw sessions cleanup --all-agents --dry-run
openclaw sessions cleanup --enforce
openclaw sessions cleanup --enforce --active-key "agent:main:telegram:direct:123"
openclaw sessions cleanup --json
```
يستخدم `openclaw sessions cleanup` إعدادات `session.maintenance` من التكوين:
- ملاحظة النطاق: يحافظ `openclaw sessions cleanup` على مخازن الجلسات/النصوص فقط. ولا يقوم بتقليم سجلات تشغيل cron (`cron/runs/<jobId>.jsonl`) التي تُدار بواسطة `cron.runLog.maxBytes` و`cron.runLog.keepLines` في [تكوين Cron](/automation/cron-jobs#configuration) والمشروحة في [صيانة Cron](/automation/cron-jobs#maintenance).
- `--dry-run`: معاينة عدد الإدخالات التي سيتم تقليمها/تقييدها من دون كتابة.
- في وضع النص، يطبع dry-run جدول إجراءات لكل جلسة (`Action` و`Key` و`Age` و`Model` و`Flags`) حتى تتمكن من معرفة ما سيتم الاحتفاظ به مقابل ما سيتم حذفه.
- `--enforce`: تطبيق الصيانة حتى عندما يكون `session.maintenance.mode` هو `warn`.
- `--fix-missing`: إزالة الإدخالات التي تفتقد ملفات النص الخاصة بها، حتى لو لم تكن ستخرج عادةً بسبب العمر/العدد بعد.
- `--active-key <key>`: حماية مفتاح نشط محدد من الإخلاء بسبب ميزانية القرص.
- `--agent <id>`: تشغيل التنظيف لمخزن وكيل مكوَّن واحد.
- `--all-agents`: تشغيل التنظيف لجميع مخازن الوكلاء المكوَّنة.
- `--store <path>`: التشغيل مقابل ملف `sessions.json` محدد.
- `--json`: طباعة ملخص JSON. ومع `--all-agents`، يتضمن الإخراج ملخصًا واحدًا لكل مخزن.
`openclaw sessions cleanup --all-agents --dry-run --json`:
```json
{
"allAgents": true,
"mode": "warn",
"dryRun": true,
"stores": [
{
"agentId": "main",
"storePath": "/home/user/.openclaw/agents/main/sessions/sessions.json",
"beforeCount": 120,
"afterCount": 80,
"pruned": 40,
"capped": 0
},
{
"agentId": "work",
"storePath": "/home/user/.openclaw/agents/work/sessions/sessions.json",
"beforeCount": 18,
"afterCount": 18,
"pruned": 0,
"capped": 0
}
]
}
```
ذو صلة:
- تكوين الجلسة: [مرجع التكوين](/gateway/configuration-reference#session)

52
docs/ar/cli/setup.md Normal file
View File

@ -0,0 +1,52 @@
---
read_when:
- أنت تجري إعداد التشغيل الأول من دون الإعداد الأولي الكامل لـ CLI
- تريد تعيين مسار مساحة العمل الافتراضي
summary: مرجع CLI للأمر `openclaw setup` (تهيئة الإعداد + مساحة العمل)
title: setup
x-i18n:
generated_at: "2026-04-05T12:39:25Z"
model: gpt-5.4
provider: openai
source_hash: f538aac341c749043ad959e35f2ed99c844ab8c3500ff59aa159d940bd301792
source_path: cli/setup.md
workflow: 15
---
# `openclaw setup`
هيّئ `~/.openclaw/openclaw.json` ومساحة عمل الوكيل.
ذو صلة:
- البدء: [البدء](/ar/start/getting-started)
- الإعداد الأولي لـ CLI: [Onboarding (CLI)](/ar/start/wizard)
## أمثلة
```bash
openclaw setup
openclaw setup --workspace ~/.openclaw/workspace
openclaw setup --wizard
openclaw setup --non-interactive --mode remote --remote-url wss://gateway-host:18789 --remote-token <token>
```
## الخيارات
- `--workspace <dir>`: دليل مساحة عمل الوكيل (يُخزَّن على أنه `agents.defaults.workspace`)
- `--wizard`: تشغيل الإعداد الأولي
- `--non-interactive`: تشغيل الإعداد الأولي من دون مطالبات
- `--mode <local|remote>`: وضع الإعداد الأولي
- `--remote-url <url>`: عنوان Gateway WebSocket URL البعيد
- `--remote-token <token>`: رمز Gateway البعيد
لتشغيل الإعداد الأولي عبر setup:
```bash
openclaw setup --wizard
```
ملاحظات:
- يهيّئ `openclaw setup` العادي الإعداد + مساحة العمل من دون تدفق الإعداد الأولي الكامل.
- يعمل الإعداد الأولي تلقائيًا عند وجود أي من علامات الإعداد الأولي (`--wizard`, `--non-interactive`, `--mode`, `--remote-url`, `--remote-token`).

66
docs/ar/cli/skills.md Normal file
View File

@ -0,0 +1,66 @@
---
read_when:
- أنت تريد معرفة المهارات المتاحة والجاهزة للتشغيل
- أنت تريد البحث عن المهارات أو تثبيتها أو تحديثها من ClawHub
- أنت تريد استكشاف أخطاء الثنائيات/متغيرات البيئة/الإعدادات المفقودة للمهارات وإصلاحها
summary: مرجع CLI للأمر `openclaw skills` (بحث/تثبيت/تحديث/قائمة/معلومات/فحص)
title: skills
x-i18n:
generated_at: "2026-04-05T12:39:31Z"
model: gpt-5.4
provider: openai
source_hash: 11af59b1b6bff19cc043acd8d67bdd4303201d3f75f23c948b83bf14882c7bb1
source_path: cli/skills.md
workflow: 15
---
# `openclaw skills`
افحص المهارات المحلية وثبّت/حدّث المهارات من ClawHub.
ذو صلة:
- نظام Skills: [Skills](/tools/skills)
- إعدادات Skills: [Skills config](/tools/skills-config)
- عمليات التثبيت من ClawHub: [ClawHub](/tools/clawhub)
## الأوامر
```bash
openclaw skills search "calendar"
openclaw skills search --limit 20 --json
openclaw skills install <slug>
openclaw skills install <slug> --version <version>
openclaw skills install <slug> --force
openclaw skills update <slug>
openclaw skills update --all
openclaw skills list
openclaw skills list --eligible
openclaw skills list --json
openclaw skills list --verbose
openclaw skills info <name>
openclaw skills info <name> --json
openclaw skills check
openclaw skills check --json
```
يستخدم `search`/`install`/`update` ClawHub مباشرةً ويثبّت في دليل
`skills/` الخاص بمساحة العمل النشطة. بينما تظل `list`/`info`/`check` تفحص
المهارات المحلية المرئية لمساحة العمل والإعدادات الحالية.
يقوم أمر CLI `install` هذا بتنزيل مجلدات Skills من ClawHub. أما
عمليات تثبيت تبعيات Skills المدعومة من Gateway والتي يتم تشغيلها من onboarding أو إعدادات Skills
فتستخدم مسار الطلب المنفصل `skills.install` بدلًا من ذلك.
ملاحظات:
- يقبل `search [query...]` استعلامًا اختياريًا؛ احذفه لتصفح موجز البحث
الافتراضي في ClawHub.
- يحدد `search --limit <n>` الحد الأقصى للنتائج المعادة.
- يؤدي `install --force` إلى الكتابة فوق مجلد Skill موجود في مساحة العمل
لنفس `slug`.
- لا يقوم `update --all` إلا بتحديث عمليات التثبيت المتتبعة من ClawHub في مساحة العمل النشطة.
- تكون `list` هي الإجراء الافتراضي عندما لا يتم توفير أمر فرعي.
- تكتب `list` و`info` و`check` مخرجاتها المعروضة إلى stdout. ومع
`--json`، فهذا يعني أن الحمولة القابلة للقراءة آليًا تبقى على stdout
من أجل الأنابيب والبرامج النصية.

42
docs/ar/cli/status.md Normal file
View File

@ -0,0 +1,42 @@
---
read_when:
- أنت تريد تشخيصًا سريعًا لصحة القنوات + أحدث مستلمي الجلسة
- أنت تريد حالة “all” قابلة للنسخ واللصق لأغراض التصحيح
summary: مرجع CLI للأمر `openclaw status` ‏(التشخيصات، والفحوصات، ولقطات الاستخدام)
title: status
x-i18n:
generated_at: "2026-04-05T12:39:39Z"
model: gpt-5.4
provider: openai
source_hash: fbe9d94fbe9938cd946ee6f293b5bd3b464b75e1ade2eacdd851788c3bffe94e
source_path: cli/status.md
workflow: 15
---
# `openclaw status`
تشخيصات للقنوات + الجلسات.
```bash
openclaw status
openclaw status --all
openclaw status --deep
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 ‏(مقتطعًا لتسهيل القراءة) من دون إيقاف إنشاء التقرير.

78
docs/ar/cli/system.md Normal file
View File

@ -0,0 +1,78 @@
---
read_when:
- تريد إدراج حدث نظام في قائمة الانتظار من دون إنشاء مهمة cron
- تحتاج إلى تمكين heartbeats أو تعطيلها
- تريد فحص إدخالات حضور النظام
summary: مرجع CLI للأمر `openclaw system` (أحداث النظام، heartbeat، والحضور)
title: system
x-i18n:
generated_at: "2026-04-05T12:39:33Z"
model: gpt-5.4
provider: openai
source_hash: a7d19afde9d9cde8a79b0bb8cec6e5673466f4cb9b575fb40111fc32f4eee5d7
source_path: cli/system.md
workflow: 15
---
# `openclaw system`
مساعدات على مستوى النظام للبوابة: إدراج أحداث النظام في قائمة الانتظار، والتحكم في heartbeats،
وعرض الحضور.
تستخدم جميع الأوامر الفرعية ضمن `system` بروتوكول Gateway RPC وتقبل علامات العميل المشتركة:
- `--url <url>`
- `--token <token>`
- `--timeout <ms>`
- `--expect-final`
## الأوامر الشائعة
```bash
openclaw system event --text "Check for urgent follow-ups" --mode now
openclaw system event --text "Check for urgent follow-ups" --url ws://127.0.0.1:18789 --token "$OPENCLAW_GATEWAY_TOKEN"
openclaw system heartbeat enable
openclaw system heartbeat last
openclaw system presence
```
## `system event`
أدرج حدث نظام في قائمة الانتظار على الجلسة **الرئيسية**. سيقوم heartbeat التالي
بحقنه كسطر `System:` داخل الـ prompt. استخدم `--mode now` لتشغيل heartbeat
فورًا؛ أما `next-heartbeat` فينتظر النبضة المجدولة التالية.
العلامات:
- `--text <text>`: نص حدث النظام المطلوب.
- `--mode <mode>`: ‏`now` أو `next-heartbeat` (الافتراضي).
- `--json`: إخراج قابل للقراءة آليًا.
- `--url` و`--token` و`--timeout` و`--expect-final`: علامات Gateway RPC المشتركة.
## `system heartbeat last|enable|disable`
عناصر التحكم في heartbeat:
- `last`: عرض آخر حدث heartbeat.
- `enable`: إعادة تشغيل heartbeats (استخدم هذا إذا كانت معطلة).
- `disable`: إيقاف heartbeats مؤقتًا.
العلامات:
- `--json`: إخراج قابل للقراءة آليًا.
- `--url` و`--token` و`--timeout` و`--expect-final`: علامات Gateway RPC المشتركة.
## `system presence`
اعرض إدخالات حضور النظام الحالية التي تعرفها البوابة (العُقد،
والمثيلات، وأسطر الحالة المشابهة).
العلامات:
- `--json`: إخراج قابل للقراءة آليًا.
- `--url` و`--token` و`--timeout` و`--expect-final`: علامات Gateway RPC المشتركة.
## ملاحظات
- يتطلب Gateway قيد التشغيل ويمكن الوصول إليها عبر التكوين الحالي لديك (محليًا أو عن بُعد).
- أحداث النظام مؤقتة ولا تستمر عبر عمليات إعادة التشغيل.

37
docs/ar/cli/tui.md Normal file
View File

@ -0,0 +1,37 @@
---
read_when:
- تريد واجهة طرفية لـ Gateway (ملائمة للاستخدام عن بُعد)
- تريد تمرير url/token/session من النصوص البرمجية
summary: مرجع CLI للأمر `openclaw tui` (واجهة طرفية متصلة بـ Gateway)
title: tui
x-i18n:
generated_at: "2026-04-05T12:39:30Z"
model: gpt-5.4
provider: openai
source_hash: 60e35062c0551f85ce0da604a915b3e1ca2514d00d840afe3b94c529304c2c1a
source_path: cli/tui.md
workflow: 15
---
# `openclaw tui`
افتح الواجهة الطرفية المتصلة بـ Gateway.
ذو صلة:
- دليل TUI: [TUI](/web/tui)
ملاحظات:
- يقوم `tui` بحل SecretRefs الخاصة بمصادقة gateway المكوّنة لمصادقة token/password عند الإمكان (موفرو `env`/`file`/`exec`).
- عند تشغيله من داخل دليل مساحة عمل وكيل مُعد، يختار TUI ذلك الوكيل تلقائيًا كمفتاح جلسة افتراضي (ما لم يكن `--session` مضبوطًا صراحةً على `agent:<id>:...`).
## أمثلة
```bash
openclaw tui
openclaw tui --url ws://127.0.0.1:18789 --token <token>
openclaw tui --session main --deliver
# عند تشغيله داخل مساحة عمل وكيل، يستنتج ذلك الوكيل تلقائيًا
openclaw tui --session bugfix
```

46
docs/ar/cli/uninstall.md Normal file
View File

@ -0,0 +1,46 @@
---
read_when:
- تريد إزالة خدمة gateway و/أو الحالة المحلية
- تريد تنفيذًا تجريبيًا أولًا
summary: مرجع CLI للأمر `openclaw uninstall` (إزالة خدمة gateway + البيانات المحلية)
title: uninstall
x-i18n:
generated_at: "2026-04-05T12:39:31Z"
model: gpt-5.4
provider: openai
source_hash: 2123a4f9c7a070ef7e13c60dafc189053ef61ce189fa4f29449dd50987c1894c
source_path: cli/uninstall.md
workflow: 15
---
# `openclaw uninstall`
إلغاء تثبيت خدمة gateway + البيانات المحلية (مع بقاء CLI).
الخيارات:
- `--service`: إزالة خدمة gateway
- `--state`: إزالة الحالة والتهيئة
- `--workspace`: إزالة أدلة workspace
- `--app`: إزالة تطبيق macOS
- `--all`: إزالة الخدمة، والحالة، وworkspace، والتطبيق
- `--yes`: تخطي مطالبات التأكيد
- `--non-interactive`: تعطيل المطالبات؛ ويتطلب `--yes`
- `--dry-run`: طباعة الإجراءات من دون إزالة الملفات
أمثلة:
```bash
openclaw backup create
openclaw uninstall
openclaw uninstall --service --yes --non-interactive
openclaw uninstall --state --workspace --yes --non-interactive
openclaw uninstall --all --yes
openclaw uninstall --dry-run
```
ملاحظات:
- شغّل `openclaw backup create` أولًا إذا كنت تريد لقطة قابلة للاستعادة قبل إزالة الحالة أو مساحات العمل.
- يُعد `--all` اختصارًا لإزالة الخدمة، والحالة، وworkspace، والتطبيق معًا.
- يتطلب `--non-interactive` الخيار `--yes`.

120
docs/ar/cli/update.md Normal file
View File

@ -0,0 +1,120 @@
---
read_when:
- تريد تحديث نسخة مصدرية بأمان
- تحتاج إلى فهم سلوك الاختصار `--update`
summary: مرجع CLI للأمر `openclaw update` ‏(تحديث آمن نسبيًا للمصدر + إعادة تشغيل تلقائية لـ gateway)
title: update
x-i18n:
generated_at: "2026-04-05T12:39:46Z"
model: gpt-5.4
provider: openai
source_hash: 12c8098654b644c3666981d379f6c018e84fde56a5420f295d78052f9001bdad
source_path: cli/update.md
workflow: 15
---
# `openclaw update`
حدّث OpenClaw بأمان وبدّل بين قنوات stable/beta/dev.
إذا قمت بالتثبيت عبر **npm/pnpm/bun** (تثبيت عام، من دون بيانات git الوصفية)،
فتتم التحديثات عبر تدفق مدير الحزم الموضح في [التحديث](/install/updating).
## الاستخدام
```bash
openclaw update
openclaw update status
openclaw update wizard
openclaw update --channel beta
openclaw update --channel dev
openclaw update --tag beta
openclaw update --tag main
openclaw update --dry-run
openclaw update --no-restart
openclaw update --yes
openclaw update --json
openclaw --update
```
## الخيارات
- `--no-restart`: تخطي إعادة تشغيل خدمة Gateway بعد تحديث ناجح.
- `--channel <stable|beta|dev>`: تعيين قناة التحديث (git + npm؛ وتُحفَظ في التكوين).
- `--tag <dist-tag|version|spec>`: تجاوز هدف الحزمة لهذا التحديث فقط. بالنسبة إلى تثبيتات الحزم، يتم تعيين `main` إلى `github:openclaw/openclaw#main`.
- `--dry-run`: معاينة إجراءات التحديث المخطط لها (القناة/الوسم/الهدف/تدفق إعادة التشغيل) من دون كتابة التكوين أو التثبيت أو مزامنة plugins أو إعادة التشغيل.
- `--json`: طباعة JSON قابل للقراءة آليًا من نوع `UpdateRunResult`.
- `--timeout <seconds>`: مهلة لكل خطوة (الافتراضي 1200 ثانية).
- `--yes`: تخطي مطالبات التأكيد (مثل تأكيد الرجوع إلى إصدار أقدم)
ملاحظة: تتطلب عمليات الرجوع إلى إصدار أقدم تأكيدًا لأن الإصدارات الأقدم قد تكسر التكوين.
## `update status`
إظهار قناة التحديث النشطة + وسم/فرع/SHA الخاص بـ git (لنسخ المصدر)، بالإضافة إلى توفر التحديث.
```bash
openclaw update status
openclaw update status --json
openclaw update status --timeout 10
```
الخيارات:
- `--json`: طباعة JSON للحالة قابل للقراءة آليًا.
- `--timeout <seconds>`: مهلة للفحوصات (الافتراضي 3 ثوانٍ).
## `update wizard`
تدفق تفاعلي لاختيار قناة تحديث وتأكيد ما إذا كان يجب إعادة تشغيل Gateway
بعد التحديث (الافتراضي هو إعادة التشغيل). إذا اخترت `dev` من دون نسخة git،
فسيعرض إنشاء واحدة.
الخيارات:
- `--timeout <seconds>`: مهلة لكل خطوة تحديث (الافتراضي `1200`)
## ما الذي يفعله
عندما تبدّل القنوات صراحةً (`--channel ...`)، يحافظ OpenClaw أيضًا على
توافق طريقة التثبيت:
- `dev` ← يضمن وجود نسخة git محلية (الافتراضي: `~/openclaw`، ويمكن التجاوز عبر `OPENCLAW_GIT_DIR`)،
ويحدّثها، ويثبت CLI العام من تلك النسخة.
- `stable` ← يثبّت من npm باستخدام `latest`.
- `beta` ← يفضل npm dist-tag ‏`beta`، لكنه يعود إلى `latest` عندما تكون beta
مفقودة أو أقدم من الإصدار المستقر الحالي.
يعيد المحدّث التلقائي لنواة Gateway (عند تمكينه عبر التكوين) استخدام مسار التحديث نفسه هذا.
## تدفق نسخة git
القنوات:
- `stable`: سحب أحدث وسم غير beta، ثم البناء + doctor.
- `beta`: يفضل أحدث وسم `-beta`، لكنه يعود إلى أحدث وسم stable
عندما تكون beta مفقودة أو أقدم.
- `dev`: سحب `main`، ثم fetch + rebase.
على مستوى عالٍ:
1. يتطلب شجرة عمل نظيفة (من دون تغييرات غير ملتزم بها).
2. يبدّل إلى القناة المحددة (وسم أو فرع).
3. يجلب من upstream ‏(لـ dev فقط).
4. لـ dev فقط: تنفيذ فحص lint مسبق + بناء TypeScript في worktree مؤقت؛ وإذا فشل الطرف الحالي، يتراجع حتى 10 التزامات للعثور على أحدث بناء نظيف.
5. يعيد rebase على الالتزام المحدد (لـ dev فقط).
6. يثبت التبعيات (يفضل pnpm؛ مع بديل npm؛ ويظل bun متاحًا كبديل توافق ثانوي).
7. يبني + يبني Control UI.
8. يشغّل `openclaw doctor` كفحص "تحديث آمن" نهائي.
9. يزامن plugins مع القناة النشطة (يستخدم dev الامتدادات المضمّنة؛ بينما يستخدم stable/beta npm) ويحدّث plugins المثبتة عبر npm.
## الاختصار `--update`
يعيد `openclaw --update` الكتابة إلى `openclaw update` (وهو مفيد للأصداف وscripts الخاصة بالمشغّل).
## راجع أيضًا
- `openclaw doctor` ‏(يعرض تشغيل التحديث أولًا على نسخ git)
- [قنوات التطوير](/install/development-channels)
- [التحديث](/install/updating)
- [مرجع CLI](/cli)

41
docs/ar/cli/voicecall.md Normal file
View File

@ -0,0 +1,41 @@
---
read_when:
- أنت تستخدم المكون الإضافي للمكالمات الصوتية وتريد نقاط دخول CLI
- تريد أمثلة سريعة للأوامر `voicecall call|continue|status|tail|expose`
summary: مرجع CLI للأمر `openclaw voicecall` (سطح أوامر المكون الإضافي للمكالمات الصوتية)
title: voicecall
x-i18n:
generated_at: "2026-04-05T12:39:34Z"
model: gpt-5.4
provider: openai
source_hash: 2c99e7a3d256e1c74a0f07faba9675cc5a88b1eb2fc6e22993caf3874d4f340a
source_path: cli/voicecall.md
workflow: 15
---
# `openclaw voicecall`
الأمر `voicecall` هو أمر يوفّره مكون إضافي. ولا يظهر إلا إذا كان المكون الإضافي للمكالمات الصوتية مثبتًا ومفعّلًا.
الوثيقة الأساسية:
- المكون الإضافي للمكالمات الصوتية: [Voice Call](/plugins/voice-call)
## الأوامر الشائعة
```bash
openclaw voicecall status --call-id <id>
openclaw voicecall call --to "+15555550123" --message "Hello" --mode notify
openclaw voicecall continue --call-id <id> --message "Any questions?"
openclaw voicecall end --call-id <id>
```
## كشف webhooks ‏(Tailscale)
```bash
openclaw voicecall expose --mode serve
openclaw voicecall expose --mode funnel
openclaw voicecall expose --mode off
```
ملاحظة أمنية: اكشف نقطة نهاية webhook فقط للشبكات التي تثق بها. ويفضَّل استخدام Tailscale Serve بدلًا من Funnel عندما يكون ذلك ممكنًا.

98
docs/ar/cli/webhooks.md Normal file
View File

@ -0,0 +1,98 @@
---
read_when:
- تريد ربط أحداث Gmail Pub/Sub بـ OpenClaw
- تريد أوامر مساعدة webhook
summary: مرجع CLI للأمر `openclaw webhooks` (مساعدات webhook + ‏Gmail Pub/Sub)
title: webhooks
x-i18n:
generated_at: "2026-04-05T12:39:39Z"
model: gpt-5.4
provider: openai
source_hash: 2b22ce879c3a94557be57919b4d2b3e92ff4d41fbae7bc88d2ab07cd4bbeac83
source_path: cli/webhooks.md
workflow: 15
---
# `openclaw webhooks`
مساعدات webhook والتكاملات (Gmail Pub/Sub، ومساعدات webhook).
ذو صلة:
- Webhooks: [Webhooks](/automation/cron-jobs#webhooks)
- Gmail Pub/Sub: [Gmail Pub/Sub](/automation/cron-jobs#gmail-pubsub-integration)
## Gmail
```bash
openclaw webhooks gmail setup --account you@example.com
openclaw webhooks gmail run
```
### `webhooks gmail setup`
تهيئة مراقبة Gmail وPub/Sub وتسليم webhook إلى OpenClaw.
مطلوب:
- `--account <email>`
الخيارات:
- `--project <id>`
- `--topic <name>`
- `--subscription <name>`
- `--label <label>`
- `--hook-url <url>`
- `--hook-token <token>`
- `--push-token <token>`
- `--bind <host>`
- `--port <port>`
- `--path <path>`
- `--include-body`
- `--max-bytes <n>`
- `--renew-minutes <n>`
- `--tailscale <funnel|serve|off>`
- `--tailscale-path <path>`
- `--tailscale-target <target>`
- `--push-endpoint <url>`
- `--json`
أمثلة:
```bash
openclaw webhooks gmail setup --account you@example.com
openclaw webhooks gmail setup --account you@example.com --project my-gcp-project --json
openclaw webhooks gmail setup --account you@example.com --hook-url https://gateway.example.com/hooks/gmail
```
### `webhooks gmail run`
شغّل `gog watch serve` بالإضافة إلى حلقة التجديد التلقائي للمراقبة.
الخيارات:
- `--account <email>`
- `--topic <topic>`
- `--subscription <name>`
- `--label <label>`
- `--hook-url <url>`
- `--hook-token <token>`
- `--push-token <token>`
- `--bind <host>`
- `--port <port>`
- `--path <path>`
- `--include-body`
- `--max-bytes <n>`
- `--renew-minutes <n>`
- `--tailscale <funnel|serve|off>`
- `--tailscale-path <path>`
- `--tailscale-target <target>`
مثال:
```bash
openclaw webhooks gmail run --account you@example.com
```
راجع [وثائق Gmail Pub/Sub](/automation/cron-jobs#gmail-pubsub-integration) للحصول على تدفق الإعداد الكامل والتفاصيل التشغيلية.

175
docs/ar/concepts/agent-loop.md Normal file
View File

@ -0,0 +1,175 @@
---
read_when:
- أنت بحاجة إلى شرح دقيق لحلقة الوكيل أو أحداث دورة الحياة
summary: دورة حياة حلقة الوكيل، والتدفقات، ودلالات الانتظار
title: حلقة الوكيل
x-i18n:
generated_at: "2026-04-05T12:40:07Z"
model: gpt-5.4
provider: openai
source_hash: 8e562e63c494881e9c345efcb93c5f972d69aaec61445afc3d4ad026b2d26883
source_path: concepts/agent-loop.md
workflow: 15
---
# حلقة الوكيل (OpenClaw)
الحلقة الوكيلية هي التشغيل الكامل "الحقيقي" للوكيل: الإدخال → تجميع السياق → استدلال النموذج →
تنفيذ الأدوات → بث الردود → الاستمرارية. وهي المسار المرجعي الذي يحوّل الرسالة
إلى إجراءات ورد نهائي، مع الحفاظ على اتساق حالة الجلسة.
في OpenClaw، تكون الحلقة تشغيلًا واحدًا متسلسلًا لكل جلسة، ويصدر أحداث دورة الحياة والتدفق
بينما يفكر النموذج، ويستدعي الأدوات، ويبث المخرجات. تشرح هذه الوثيقة كيف يتم
توصيل تلك الحلقة الأصلية من البداية إلى النهاية.
## نقاط الدخول
- Gateway RPC: ‏`agent` و`agent.wait`.
- CLI: الأمر `agent`.
## كيف يعمل (نظرة عامة عالية المستوى)
1. يتحقق RPC `agent` من المعلمات، ويحل الجلسة (`sessionKey/sessionId`)، ويحفظ بيانات تعريف الجلسة، ويعيد `{ runId, acceptedAt }` فورًا.
2. يشغّل `agentCommand` الوكيل:
- يحل الإعدادات الافتراضية للنموذج + thinking/verbose
- يحمّل لقطة Skills
- يستدعي `runEmbeddedPiAgent` (وقت تشغيل pi-agent-core)
- يصدر **lifecycle end/error** إذا لم تصدرها الحلقة المضمنة
3. يقوم `runEmbeddedPiAgent` بما يلي:
- يسلسل عمليات التشغيل عبر قوائم انتظار لكل جلسة + قائمة انتظار عامة
- يحل ملف تعريف النموذج + auth ويبني جلسة Pi
- يشترك في أحداث Pi ويبث فروق assistant/tool
- يفرض مهلة -> يوقف التشغيل إذا تم تجاوزها
- يعيد الحمولات + بيانات تعريف الاستخدام
4. يقوم `subscribeEmbeddedPiSession` بربط أحداث pi-agent-core بتدفق OpenClaw `agent`:
- أحداث الأدوات => `stream: "tool"`
- فروق المساعد => `stream: "assistant"`
- أحداث دورة الحياة => `stream: "lifecycle"` (`phase: "start" | "end" | "error"`)
5. يستخدم `agent.wait` الدالة `waitForAgentRun`:
- ينتظر **lifecycle end/error** لـ `runId`
- يعيد `{ status: ok|error|timeout, startedAt, endedAt, error? }`
## الاصطفاف + التوازي
- يتم تسلسل عمليات التشغيل لكل مفتاح جلسة (مسار الجلسة) واختياريًا عبر مسار عام.
- يمنع هذا تضاربات الأدوات/الجلسات ويحافظ على اتساق سجل الجلسة.
- يمكن لقنوات المراسلة اختيار أوضاع الاصطفاف (collect/steer/followup) التي تغذي نظام المسارات هذا.
راجع [Command Queue](/concepts/queue).
## إعداد الجلسة + مساحة العمل
- يتم حل مساحة العمل وإنشاؤها؛ وقد تعيد عمليات التشغيل المعزولة التوجيه إلى جذر مساحة عمل معزول.
- يتم تحميل Skills (أو إعادة استخدامها من لقطة) وحقنها في env وprompt.
- يتم حل ملفات bootstrap/context وحقنها في تقرير system prompt.
- يتم الحصول على قفل كتابة للجلسة؛ ويتم فتح `SessionManager` وإعداده قبل البث.
## تجميع prompt + system prompt
- يتم بناء system prompt من prompt الأساسي في OpenClaw، وprompt الخاص بـ Skills، وسياق bootstrap، والتجاوزات الخاصة بكل تشغيل.
- تُفرض الحدود الخاصة بالنموذج ورموز الحجز الخاصة بالضغط.
- راجع [System prompt](/concepts/system-prompt) لمعرفة ما يراه النموذج.
## نقاط hook (حيث يمكنك الاعتراض)
يحتوي OpenClaw على نظامي hook:
- **hooks داخلية** (Gateway hooks): برامج نصية مدفوعة بالأحداث للأوامر وأحداث دورة الحياة.
- **Plugin hooks**: نقاط امتداد داخل دورة حياة الوكيل/الأداة ومسار Gateway.
### hooks داخلية (Gateway hooks)
- **`agent:bootstrap`**: تعمل أثناء إنشاء ملفات bootstrap قبل الانتهاء من system prompt.
استخدمها لإضافة/إزالة ملفات سياق bootstrap.
- **hooks الأوامر**: `/new` و`/reset` و`/stop` وأحداث الأوامر الأخرى (راجع وثيقة Hooks).
راجع [Hooks](/automation/hooks) للحصول على الإعداد والأمثلة.
### Plugin hooks (دورة حياة الوكيل + Gateway)
تعمل هذه داخل حلقة الوكيل أو مسار Gateway:
- **`before_model_resolve`**: تعمل قبل الجلسة (من دون `messages`) لتجاوز provider/model بشكل حتمي قبل حل النموذج.
- **`before_prompt_build`**: تعمل بعد تحميل الجلسة (مع `messages`) لحقن `prependContext` أو `systemPrompt` أو `prependSystemContext` أو `appendSystemContext` قبل إرسال prompt. استخدم `prependContext` للنصوص الديناميكية لكل دور، واستخدم حقول سياق النظام للإرشاد الثابت الذي يجب أن يوجد ضمن مساحة system prompt.
- **`before_agent_start`**: hook توافقية قديمة قد تعمل في أي من المرحلتين؛ ويفضل استخدام hooks الصريحة أعلاه.
- **`before_agent_reply`**: تعمل بعد الإجراءات المضمنة وقبل استدعاء LLM، مما يسمح لإضافة بالمطالبة بالدور وإرجاع رد اصطناعي أو إسكات الدور بالكامل.
- **`agent_end`**: افحص قائمة الرسائل النهائية وبيانات تعريف التشغيل بعد الاكتمال.
- **`before_compaction` / `after_compaction`**: راقب دورات الضغط أو أضف تعليقات توضيحية إليها.
- **`before_tool_call` / `after_tool_call`**: اعترض معلمات/نتائج الأدوات.
- **`before_install`**: افحص نتائج المسح المضمنة ويمكنك اختياريًا حظر تثبيت Skill أو plugin.
- **`tool_result_persist`**: حوّل نتائج الأدوات بشكل متزامن قبل كتابتها إلى نص الجلسة.
- **`message_received` / `message_sending` / `message_sent`**: hooks للرسائل الواردة + الصادرة.
- **`session_start` / `session_end`**: حدود دورة حياة الجلسة.
- **`gateway_start` / `gateway_stop`**: أحداث دورة حياة Gateway.
قواعد قرارات hook لحواجز الخروج/الأدوات:
- `before_tool_call`: تكون `{ block: true }` نهائية وتوقف المعالجات ذات الأولوية الأدنى.
- `before_tool_call`: تكون `{ block: false }` بلا تأثير ولا تلغي حظرًا سابقًا.
- `before_install`: تكون `{ block: true }` نهائية وتوقف المعالجات ذات الأولوية الأدنى.
- `before_install`: تكون `{ block: false }` بلا تأثير ولا تلغي حظرًا سابقًا.
- `message_sending`: تكون `{ cancel: true }` نهائية وتوقف المعالجات ذات الأولوية الأدنى.
- `message_sending`: تكون `{ cancel: false }` بلا تأثير ولا تلغي إلغاءً سابقًا.
راجع [Plugin hooks](/plugins/architecture#provider-runtime-hooks) للاطلاع على API الخاص بالـ hook وتفاصيل التسجيل.
## البث + الردود الجزئية
- يتم بث فروق المساعد من pi-agent-core وإصدارها كأحداث `assistant`.
- يمكن لبث الكتل إصدار ردود جزئية إما عند `text_end` أو `message_end`.
- يمكن إصدار بث الاستدلال كتدفق منفصل أو كردود كتلية.
- راجع [Streaming](/concepts/streaming) لسلوك التجزئة وردود الكتل.
## تنفيذ الأدوات + أدوات المراسلة
- يتم إصدار أحداث بدء/تحديث/انتهاء الأداة على تدفق `tool`.
- يتم تنظيف نتائج الأدوات من حيث الحجم وحمولات الصور قبل التسجيل/الإصدار.
- يتم تتبع عمليات الإرسال عبر أدوات المراسلة لمنع تأكيدات المساعد المكررة.
## تشكيل الرد + الكبت
- يتم تجميع الحمولات النهائية من:
- نص المساعد (واستدلال اختياري)
- ملخصات الأدوات المضمنة (عند verbose + عند السماح)
- نص خطأ المساعد عند حدوث خطأ في النموذج
- تتم تصفية الرمز الصامت المطابق تمامًا `NO_REPLY` / `no_reply` من الحمولات
الصادرة.
- تتم إزالة تكرارات أدوات المراسلة من قائمة الحمولات النهائية.
- إذا لم تبق أي حمولات قابلة للعرض وحدث خطأ في أداة، يتم إصدار
رد احتياطي لخطأ الأداة (ما لم تكن أداة مراسلة قد أرسلت بالفعل ردًا مرئيًا للمستخدم).
## الضغط + إعادة المحاولة
- يصدر الضغط التلقائي أحداث تدفق `compaction` ويمكن أن يؤدي إلى إعادة المحاولة.
- عند إعادة المحاولة، تتم إعادة تعيين المخازن داخل الذاكرة وملخصات الأدوات لتجنب المخرجات المكررة.
- راجع [Compaction](/concepts/compaction) للاطلاع على مسار الضغط.
## تدفقات الأحداث (حاليًا)
- `lifecycle`: يصدره `subscribeEmbeddedPiSession` (وكحل احتياطي بواسطة `agentCommand`)
- `assistant`: فروق مبثوثة من pi-agent-core
- `tool`: أحداث أدوات مبثوثة من pi-agent-core
## التعامل مع قنوات الدردشة
- يتم تخزين فروق المساعد مؤقتًا في رسائل `delta` للدردشة.
- يتم إصدار `final` للدردشة عند **lifecycle end/error**.
## المهلات
- الافتراضي لـ `agent.wait`: ‏30 ثانية (الانتظار فقط). تتجاوزها المعلمة `timeoutMs`.
- وقت تشغيل الوكيل: الافتراضي لـ `agents.defaults.timeoutSeconds` هو 172800 ثانية (48 ساعة)؛ ويتم فرضه في `runEmbeddedPiAgent` عبر مؤقت إيقاف.
## أين يمكن أن تنتهي الأمور مبكرًا
- مهلة الوكيل (إيقاف)
- `AbortSignal` (إلغاء)
- انقطاع Gateway أو مهلة RPC
- مهلة `agent.wait` (للانتظار فقط، ولا توقف الوكيل)
## ذو صلة
- [الأدوات](/tools) — أدوات الوكيل المتاحة
- [Hooks](/automation/hooks) — برامج نصية مدفوعة بالأحداث يتم تشغيلها بواسطة أحداث دورة حياة الوكيل
- [Compaction](/concepts/compaction) — كيف يتم تلخيص المحادثات الطويلة
- [Exec Approvals](/tools/exec-approvals) — بوابات الموافقة لأوامر shell
- [Thinking](/tools/thinking) — إعداد مستوى thinking/reasoning

254
docs/ar/concepts/agent-workspace.md Normal file
View File

@ -0,0 +1,254 @@
---
read_when:
- تحتاج إلى شرح مساحة عمل الوكيل أو بنية ملفاتها
- تريد نسخ مساحة عمل الوكيل احتياطيًا أو ترحيلها
summary: 'مساحة عمل الوكيل: الموقع، والبنية، واستراتيجية النسخ الاحتياطي'
title: مساحة عمل الوكيل
x-i18n:
generated_at: "2026-04-05T12:40:04Z"
model: gpt-5.4
provider: openai
source_hash: 3735633f1098c733415369f9836fdbbc0bf869636a24ed42e95e6784610d964a
source_path: concepts/agent-workspace.md
workflow: 15
---
# مساحة عمل الوكيل
مساحة العمل هي موطن الوكيل. وهي دليل العمل الوحيد المستخدم لأدوات
الملفات ولسياق مساحة العمل. حافظ على خصوصيتها وتعامل معها على أنها ذاكرة.
وهذا منفصل عن `~/.openclaw/`، الذي يخزّن التكوين وبيانات الاعتماد
والجلسات.
**مهم:** مساحة العمل هي **الدليل الحالي الافتراضي**، وليست sandbox صارمة. تقوم
الأدوات بحل المسارات النسبية اعتمادًا على مساحة العمل، لكن لا تزال المسارات المطلقة
قادرة على الوصول إلى أماكن أخرى على المضيف ما لم يتم تمكين sandboxing. إذا كنت
تحتاج إلى العزل، فاستخدم
[`agents.defaults.sandbox`](/gateway/sandboxing) (و/أو تكوين sandbox لكل وكيل).
عند تمكين sandboxing وعندما لا تكون `workspaceAccess` مساوية لـ `"rw"`، تعمل الأدوات
داخل مساحة عمل sandbox ضمن `~/.openclaw/sandboxes`، وليس داخل مساحة عمل المضيف.
## الموقع الافتراضي
- الافتراضي: `~/.openclaw/workspace`
- إذا تم ضبط `OPENCLAW_PROFILE` ولم تكن قيمته `"default"`، يصبح الافتراضي
`~/.openclaw/workspace-<profile>`.
- يمكنك التجاوز في `~/.openclaw/openclaw.json`:
```json5
{
agent: {
workspace: "~/.openclaw/workspace",
},
}
```
سيقوم `openclaw onboard` أو `openclaw configure` أو `openclaw setup` بإنشاء
مساحة العمل وتهيئة ملفات bootstrap إذا كانت مفقودة.
لا تقبل نسخ seed الخاصة بـ sandbox إلا الملفات العادية داخل مساحة العمل؛ ويتم تجاهل
الأسماء البديلة من symlink/hardlink التي تُحل خارج مساحة العمل المصدر.
إذا كنت تدير ملفات مساحة العمل بنفسك بالفعل، فيمكنك تعطيل إنشاء
ملفات bootstrap:
```json5
{ agent: { skipBootstrap: true } }
```
## مجلدات مساحة العمل الإضافية
قد تكون عمليات التثبيت الأقدم قد أنشأت `~/openclaw`. وقد يؤدي الاحتفاظ بعدة
أدلة لمساحة العمل إلى حدوث انحرافات مربكة في المصادقة أو الحالة، لأن
مساحة عمل واحدة فقط تكون نشطة في كل مرة.
**التوصية:** احتفظ بمساحة عمل نشطة واحدة. وإذا لم تعد تستخدم
المجلدات الإضافية، فأرشفها أو انقلها إلى سلة المهملات (مثل `trash ~/openclaw`).
إذا كنت تحتفظ عمدًا بعدة مساحات عمل، فتأكد من أن
`agents.defaults.workspace` يشير إلى النشطة منها.
يعرض `openclaw doctor` تحذيرًا عندما يكتشف أدلة إضافية لمساحة العمل.
## خريطة ملفات مساحة العمل (ما الذي يعنيه كل ملف)
هذه هي الملفات القياسية التي يتوقعها OpenClaw داخل مساحة العمل:
- `AGENTS.md`
- تعليمات تشغيلية للوكيل وكيفية استخدامه للذاكرة.
- يُحمَّل في بداية كل جلسة.
- مكان مناسب للقواعد والأولويات وتفاصيل "كيفية التصرف".
- `SOUL.md`
- الشخصية، والنبرة، والحدود.
- يُحمَّل في كل جلسة.
- الدليل: [دليل شخصية SOUL.md](/concepts/soul)
- `USER.md`
- من هو المستخدم وكيفية مخاطبته.
- يُحمَّل في كل جلسة.
- `IDENTITY.md`
- اسم الوكيل وطابعه وemoji الخاص به.
- يُنشأ/يُحدَّث أثناء طقس bootstrap.
- `TOOLS.md`
- ملاحظات حول أدواتك المحلية والاصطلاحات الخاصة بك.
- لا يتحكم في توفر الأدوات؛ فهو مجرد إرشاد.
- `HEARTBEAT.md`
- قائمة تحقق صغيرة اختيارية لتشغيلات heartbeat.
- اجعله قصيرًا لتجنب استهلاك token.
- `BOOT.md`
- قائمة تحقق اختيارية عند بدء التشغيل تُنفذ عند إعادة تشغيل البوابة عندما تكون hooks الداخلية مفعلة.
- اجعلها قصيرة؛ واستخدم أداة الرسائل للإرسال الصادر.
- `BOOTSTRAP.md`
- طقس تشغيل أولي لمرة واحدة.
- لا يُنشأ إلا لمساحة عمل جديدة تمامًا.
- احذفه بعد اكتمال الطقس.
- `memory/YYYY-MM-DD.md`
- سجل ذاكرة يومي (ملف واحد لكل يوم).
- يُنصح بقراءة ملف اليوم + الأمس عند بدء الجلسة.
- `MEMORY.md` (اختياري)
- ذاكرة طويلة المدى منسقة.
- لا تُحمَّل إلا في الجلسة الرئيسية الخاصة (وليس في السياقات المشتركة/الجماعية).
راجع [الذاكرة](/concepts/memory) لمعرفة سير العمل والتفريغ التلقائي للذاكرة.
- `skills/` (اختياري)
- Skills خاصة بمساحة العمل.
- موقع Skills الأعلى أولوية لتلك المساحة.
- يتجاوز Skills وكيل المشروع، وSkills الوكيل الشخصية، وSkills المُدارة، وSkills المضمنة، و`skills.load.extraDirs` عند تعارض الأسماء.
- `canvas/` (اختياري)
- ملفات واجهة Canvas لعرض العُقد (مثل `canvas/index.html`).
إذا كان أي ملف bootstrap مفقودًا، فسيحقن OpenClaw علامة "ملف مفقود" داخل
الجلسة ويتابع العمل. وتُقتطع ملفات bootstrap الكبيرة عند حقنها؛ ويمكنك
تعديل الحدود باستخدام `agents.defaults.bootstrapMaxChars` (الافتراضي: 20000) و
`agents.defaults.bootstrapTotalMaxChars` (الافتراضي: 150000).
يمكن لـ `openclaw setup` إعادة إنشاء الإعدادات الافتراضية المفقودة من دون الكتابة فوق
الملفات الموجودة.
## ما الذي لا يوجد في مساحة العمل
توجد هذه العناصر ضمن `~/.openclaw/` ويجب **عدم** الالتزام بها في مستودع مساحة العمل:
- `~/.openclaw/openclaw.json` (التكوين)
- `~/.openclaw/agents/<agentId>/agent/auth-profiles.json` (ملفات تعريف مصادقة النماذج: OAuth + مفاتيح API)
- `~/.openclaw/credentials/` (حالة القنوات/المزوّدين بالإضافة إلى بيانات استيراد OAuth القديمة)
- `~/.openclaw/agents/<agentId>/sessions/` (نصوص الجلسات + البيانات الوصفية)
- `~/.openclaw/skills/` (Skills مُدارة)
إذا كنت تحتاج إلى ترحيل الجلسات أو التكوين، فانسخها بشكل منفصل وأبقها
خارج version control.
## النسخ الاحتياطي باستخدام Git (موصى به، خاص)
تعامل مع مساحة العمل على أنها ذاكرة خاصة. ضعها في مستودع git **خاص**
حتى تكون منسوخة احتياطيًا وقابلة للاستعادة.
نفّذ هذه الخطوات على الجهاز الذي تعمل عليه البوابة (فهناك توجد
مساحة العمل).
### 1) تهيئة المستودع
إذا كان git مثبتًا، فستتم تهيئة مساحات العمل الجديدة تمامًا تلقائيًا. وإذا لم تكن
مساحة العمل هذه مستودعًا بالفعل، فشغّل:
```bash
cd ~/.openclaw/workspace
git init
git add AGENTS.md SOUL.md TOOLS.md IDENTITY.md USER.md HEARTBEAT.md memory/
git commit -m "Add agent workspace"
```
### 2) أضف remote خاصًا (خيارات مناسبة للمبتدئين)
الخيار A: واجهة GitHub على الويب
1. أنشئ مستودعًا جديدًا **خاصًا** على GitHub.
2. لا تهيّئه بملف README (لتجنب تعارضات الدمج).
3. انسخ عنوان remote بنمط HTTPS.
4. أضف remote وادفع التغييرات:
```bash
git branch -M main
git remote add origin <https-url>
git push -u origin main
```
الخيار B: GitHub CLI (`gh`)
```bash
gh auth login
gh repo create openclaw-workspace --private --source . --remote origin --push
```
الخيار C: واجهة GitLab على الويب
1. أنشئ مستودعًا جديدًا **خاصًا** على GitLab.
2. لا تهيّئه بملف README (لتجنب تعارضات الدمج).
3. انسخ عنوان remote بنمط HTTPS.
4. أضف remote وادفع التغييرات:
```bash
git branch -M main
git remote add origin <https-url>
git push -u origin main
```
### 3) التحديثات المستمرة
```bash
git status
git add .
git commit -m "Update memory"
git push
```
## لا تلتزم بالأسرار
حتى في المستودع الخاص، تجنب تخزين الأسرار في مساحة العمل:
- مفاتيح API أو OAuth tokens أو كلمات المرور أو بيانات الاعتماد الخاصة.
- أي شيء ضمن `~/.openclaw/`.
- عمليات تفريغ خام للدردشات أو المرفقات الحساسة.
إذا اضطررت إلى تخزين مراجع حساسة، فاستخدم عناصر نائبة واحتفظ بالسر
الحقيقي في مكان آخر (مدير كلمات المرور، أو متغيرات البيئة، أو `~/.openclaw/`).
بداية مقترحة لملف `.gitignore`:
```gitignore
.DS_Store
.env
**/*.key
**/*.pem
**/secrets*
```
## نقل مساحة العمل إلى جهاز جديد
1. انسخ المستودع إلى المسار المطلوب (الافتراضي `~/.openclaw/workspace`).
2. اضبط `agents.defaults.workspace` على ذلك المسار في `~/.openclaw/openclaw.json`.
3. شغّل `openclaw setup --workspace <path>` لتهيئة أي ملفات مفقودة.
4. إذا كنت تحتاج إلى الجلسات، فانقل `~/.openclaw/agents/<agentId>/sessions/` من
الجهاز القديم بشكل منفصل.
## ملاحظات متقدمة
- يمكن أن يستخدم التوجيه متعدد الوكلاء مساحات عمل مختلفة لكل وكيل. راجع
[توجيه القنوات](/channels/channel-routing) لمعرفة تكوين التوجيه.
- إذا كان `agents.defaults.sandbox` مفعّلًا، فيمكن للجلسات غير الرئيسية استخدام
مساحات عمل sandbox لكل جلسة ضمن `agents.defaults.sandbox.workspaceRoot`.
## ذو صلة
- [الأوامر الدائمة](/automation/standing-orders) — تعليمات مستمرة في ملفات مساحة العمل
- [Heartbeat](/gateway/heartbeat) — ملف مساحة العمل HEARTBEAT.md
- [الجلسة](/concepts/session) — مسارات تخزين الجلسات
- [Sandboxing](/gateway/sandboxing) — وصول مساحة العمل في البيئات المعزولة

136
docs/ar/concepts/agent.md Normal file
View File

@ -0,0 +1,136 @@
---
read_when:
- تغيير وقت تشغيل الوكيل، أو تهيئة مساحة العمل، أو سلوك الجلسة
summary: وقت تشغيل الوكيل، وعقد مساحة العمل، وتهيئة الجلسة
title: وقت تشغيل الوكيل
x-i18n:
generated_at: "2026-04-05T12:39:52Z"
model: gpt-5.4
provider: openai
source_hash: e2ff39f4114f009e5b1f86894ea4bb29b1c9512563b70d063f09ca7cde5e8948
source_path: concepts/agent.md
workflow: 15
---
# وقت تشغيل الوكيل
يشغّل OpenClaw وقت تشغيل وكيل مضمّنًا واحدًا.
## مساحة العمل (مطلوبة)
يستخدم OpenClaw دليل مساحة عمل وكيل واحدًا (`agents.defaults.workspace`) باعتباره دليل العمل **الوحيد** للوكيل (`cwd`) للأدوات والسياق.
الموصى به: استخدم `openclaw setup` لإنشاء `~/.openclaw/openclaw.json` إذا كان مفقودًا وتهيئة ملفات مساحة العمل.
تخطيط مساحة العمل الكامل + دليل النسخ الاحتياطي: [مساحة عمل الوكيل](/concepts/agent-workspace)
إذا كان `agents.defaults.sandbox` مفعّلًا، يمكن للجلسات غير الرئيسية تجاوز ذلك باستخدام
مساحات عمل لكل جلسة ضمن `agents.defaults.sandbox.workspaceRoot` (راجع
[Gateway configuration](/gateway/configuration)).
## ملفات التهيئة الأولية (محقونة)
داخل `agents.defaults.workspace`، يتوقع OpenClaw هذه الملفات القابلة للتحرير من قبل المستخدم:
- `AGENTS.md` — تعليمات التشغيل + “الذاكرة”
- `SOUL.md` — الشخصية، والحدود، والنبرة
- `TOOLS.md` — ملاحظات الأدوات التي يحتفظ بها المستخدم (مثل `imsg` و`sag` والاتفاقيات)
- `BOOTSTRAP.md` — طقس التشغيل الأول لمرة واحدة (يُحذف بعد الاكتمال)
- `IDENTITY.md` — اسم الوكيل/أسلوبه/الرمز التعبيري
- `USER.md` — ملف تعريف المستخدم + أسلوب المخاطبة المفضل
في الدور الأول من جلسة جديدة، يحقن OpenClaw محتويات هذه الملفات مباشرة في سياق الوكيل.
يتم تخطي الملفات الفارغة. وتُقص الملفات الكبيرة وتُختصر مع علامة حتى تبقى الموجّهات خفيفة (اقرأ الملف لرؤية المحتوى الكامل).
إذا كان ملف ما مفقودًا، يحقن OpenClaw سطر علامة واحدًا يشير إلى “ملف مفقود” (وسينشئ `openclaw setup` قالبًا افتراضيًا آمنًا).
لا يُنشأ `BOOTSTRAP.md` إلا لمساحة عمل **جديدة تمامًا** (عندما لا توجد ملفات تهيئة أولية أخرى). وإذا حذفته بعد إكمال الطقس، فلا ينبغي إعادة إنشائه عند إعادة التشغيل لاحقًا.
لتعطيل إنشاء ملفات التهيئة الأولية بالكامل (لمساحات العمل المُجهزة مسبقًا)، اضبط:
```json5
{ agent: { skipBootstrap: true } }
```
## الأدوات المضمّنة
الأدوات الأساسية (read/exec/edit/write وأدوات النظام ذات الصلة) متاحة دائمًا،
مع الخضوع لسياسة الأدوات. وتكون `apply_patch` اختيارية ومقيّدة بواسطة
`tools.exec.applyPatch`. لا يتحكم `TOOLS.md` في الأدوات الموجودة؛ بل هو
إرشاد لكيفية _رغبتك_ في استخدامها.
## Skills
يحمّل OpenClaw Skills من هذه المواقع (الأولوية الأعلى أولًا):
- مساحة العمل: `<workspace>/skills`
- Skills وكيل المشروع: `<workspace>/.agents/skills`
- Skills الوكيل الشخصية: `~/.agents/skills`
- المُدارة/المحلية: `~/.openclaw/skills`
- المضمّنة (المشحونة مع التثبيت)
- مجلدات Skills إضافية: `skills.load.extraDirs`
يمكن تقييد Skills عبر الإعداد/البيئة (راجع `skills` في [Gateway configuration](/gateway/configuration)).
## حدود وقت التشغيل
وقت تشغيل الوكيل المضمّن مبني على Pi agent core (النماذج، والأدوات،
وسير عمل الموجّه). أما إدارة الجلسات، والاكتشاف، وربط الأدوات، وتسليم القنوات،
فهي طبقات يملكها OpenClaw فوق ذلك الأساس.
## الجلسات
تُخزَّن نصوص الجلسات بصيغة JSONL في:
- `~/.openclaw/agents/<agentId>/sessions/<SessionId>.jsonl`
يكون معرّف الجلسة ثابتًا ويختاره OpenClaw.
ولا تُقرأ مجلدات الجلسات القديمة من أدوات أخرى.
## التوجيه أثناء البث
عندما يكون وضع قائمة الانتظار `steer`، تُحقن الرسائل الواردة في التشغيل الحالي.
ويُسلَّم التوجيه الموضوع في قائمة الانتظار **بعد أن ينهي دور المساعد الحالي
تنفيذ استدعاءات أدواته**، وقبل استدعاء LLM التالي. ولم يعد التوجيه يتخطى
استدعاءات الأدوات المتبقية من رسالة المساعد الحالية؛ بل يحقن الرسالة
الموضوعة في قائمة الانتظار عند حد النموذج التالي بدلًا من ذلك.
عندما يكون وضع قائمة الانتظار `followup` أو `collect`، تُحتجز الرسائل الواردة حتى
ينتهي الدور الحالي، ثم يبدأ دور وكيل جديد مع الحمولات الموضوعة في قائمة الانتظار. راجع
[Queue](/concepts/queue) لسلوك الوضع + إزالة الارتداد/الحد الأقصى.
يرسل بث الكتل كتل المساعد المكتملة بمجرد انتهائها؛ وهو
**معطّل افتراضيًا** (`agents.defaults.blockStreamingDefault: "off"`).
اضبط الحد عبر `agents.defaults.blockStreamingBreak` ‏(`text_end` مقابل `message_end`؛ والافتراضي هو text_end).
وتحكم في تجزئة الكتل المرنة عبر `agents.defaults.blockStreamingChunk` (الافتراضي
800–1200 حرفًا؛ ويفضّل فواصل الفقرات، ثم الأسطر الجديدة؛ وأخيرًا الجمل).
واجمع الأجزاء المتدفقة عبر `agents.defaults.blockStreamingCoalesce` لتقليل
الرسائل المزعجة أحادية السطر (دمج يعتمد على الخمول قبل الإرسال). وتتطلب القنوات غير
Telegram ضبطًا صريحًا لـ `*.blockStreaming: true` لتفعيل ردود الكتل.
وتُصدر ملخصات الأدوات المفصلة عند بدء الأداة (من دون إزالة ارتداد)؛ بينما تقوم Control UI
ببث مخرجات الأدوات عبر أحداث الوكيل عند توفرها.
مزيد من التفاصيل: [البث + التجزئة](/concepts/streaming).
## مراجع النماذج
تُحلَّل مراجع النماذج في الإعداد (مثل `agents.defaults.model` و`agents.defaults.models`) بالتقسيم عند **أول** `/`.
- استخدم `provider/model` عند إعداد النماذج.
- إذا كان معرّف النموذج نفسه يحتوي على `/` (بنمط OpenRouter)، فأدرج بادئة المزوّد (مثال: `openrouter/moonshotai/kimi-k2`).
- إذا حذفت المزوّد، يحاول OpenClaw أولًا استخدام اسم بديل، ثم تطابقًا فريدًا
لمزوّد مُعد لذلك المعرّف الدقيق للنموذج، وبعدها فقط يعود
إلى المزوّد الافتراضي المُعد. وإذا لم يعد ذلك المزوّد يوفّر
النموذج الافتراضي المُعد، يعود OpenClaw إلى أول
مزوّد/نموذج مُعد بدلًا من إظهار قيمة افتراضية قديمة من مزوّد محذوف.
## الإعداد (الحد الأدنى)
كحد أدنى، اضبط:
- `agents.defaults.workspace`
- `channels.whatsapp.allowFrom` ‏(موصى به بشدة)
---
_التالي: [دردشات المجموعات](/channels/group-messages)_ 🦞

161
docs/ar/concepts/architecture.md Normal file
View File

@ -0,0 +1,161 @@
---
read_when:
- العمل على بروتوكول gateway أو العملاء أو وسائل النقل
summary: بنية Gateway عبر WebSocket، والمكونات، وتدفقات العملاء
title: بنية Gateway
x-i18n:
generated_at: "2026-04-05T12:40:04Z"
model: gpt-5.4
provider: openai
source_hash: 2b12a2a29e94334c6d10787ac85c34b5b046f9a14f3dd53be453368ca4a7547d
source_path: concepts/architecture.md
workflow: 15
---
# بنية Gateway
## نظرة عامة
- يمتلك **Gateway** واحد طويل العمر جميع أسطح المراسلة (WhatsApp عبر
Baileys، وTelegram عبر grammY، وSlack، وDiscord، وSignal، وiMessage، وWebChat).
- يتصل عملاء مستوى التحكم (تطبيق macOS، وCLI، وواجهة الويب، وعمليات الأتمتة) بـ
Gateway عبر **WebSocket** على مضيف الربط المهيأ (الافتراضي
`127.0.0.1:18789`).
- تتصل **العقد** (macOS/iOS/Android/بلا واجهة) أيضًا عبر **WebSocket**، ولكن
تعلن `role: node` مع قدرات/أوامر صريحة.
- Gateway واحد لكل مضيف؛ وهو المكان الوحيد الذي يفتح جلسة WhatsApp.
- يتم تقديم **مضيف canvas** بواسطة خادم HTTP الخاص بـ Gateway تحت:
- `/__openclaw__/canvas/` ‏(HTML/CSS/JS قابل للتحرير بواسطة الوكيل)
- `/__openclaw__/a2ui/` ‏(مضيف A2UI)
ويستخدم المنفذ نفسه الخاص بـ Gateway (الافتراضي `18789`).
## المكونات والتدفقات
### Gateway ‏(daemon)
- يحافظ على اتصالات المزوّدين.
- يكشف WS API مكتوبة الأنواع (طلبات، واستجابات، وأحداث دفع من الخادم).
- يتحقق من الإطارات الواردة مقابل JSON Schema.
- يصدر أحداثًا مثل `agent` و`chat` و`presence` و`health` و`heartbeat` و`cron`.
### العملاء (تطبيق mac / CLI / إدارة الويب)
- اتصال WS واحد لكل عميل.
- يرسلون طلبات (`health` و`status` و`send` و`agent` و`system-presence`).
- يشتركون في الأحداث (`tick` و`agent` و`presence` و`shutdown`).
### العقد (macOS / iOS / Android / بلا واجهة)
- تتصل بـ **خادم WS نفسه** مع `role: node`.
- توفّر هوية جهاز في `connect`؛ ويكون الاقتران **قائمًا على الجهاز** (الدور `node`) وتوجد
الموافقة في مخزن اقتران الأجهزة.
- تكشف أوامر مثل `canvas.*` و`camera.*` و`screen.record` و`location.get`.
تفاصيل البروتوكول:
- [بروتوكول Gateway](/gateway/protocol)
### WebChat
- واجهة ثابتة تستخدم Gateway WS API لسجل الدردشة وعمليات الإرسال.
- في الإعدادات البعيدة، تتصل عبر نفق SSH/Tailscale نفسه مثل بقية
العملاء.
## دورة حياة الاتصال (عميل واحد)
```mermaid
sequenceDiagram
participant Client
participant Gateway
Client->>Gateway: req:connect
Gateway-->>Client: res (ok)
Note right of Gateway: or res error + close
Note left of Client: payload=hello-ok<br>snapshot: presence + health
Gateway-->>Client: event:presence
Gateway-->>Client: event:tick
Client->>Gateway: req:agent
Gateway-->>Client: res:agent<br>ack {runId, status:"accepted"}
Gateway-->>Client: event:agent<br>(streaming)
Gateway-->>Client: res:agent<br>final {runId, status, summary}
```
## البروتوكول على السلك (ملخص)
- النقل: WebSocket، وإطارات نصية بحمولة JSON.
- يجب أن يكون الإطار الأول **`connect`**.
- بعد المصافحة:
- الطلبات: `{type:"req", id, method, params}` → `{type:"res", id, ok, payload|error}`
- الأحداث: `{type:"event", event, payload, seq?, stateVersion?}`
- إن `hello-ok.features.methods` / `events` هي بيانات وصفية للاكتشاف، وليست
تفريغًا مولدًا لكل مسار مساعد قابل للاستدعاء.
- تستخدم المصادقة بالسر المشترك `connect.params.auth.token` أو
`connect.params.auth.password`، وفقًا لوضع مصادقة gateway المهيأ.
- تستوفي الأوضاع الحاملة للهوية مثل Tailscale Serve
(`gateway.auth.allowTailscale: true`) أو الربط غير المحلي
`gateway.auth.mode: "trusted-proxy"` المصادقة من ترويسات الطلب
بدلًا من `connect.params.auth.*`.
- يقوم `gateway.auth.mode: "none"` في الإدخال الخاص بتعطيل مصادقة السر المشترك
بالكامل؛ وأبقِ هذا الوضع معطّلًا على الإدخالات العامة/غير الموثوقة.
- مفاتيح idempotency مطلوبة للطرق ذات الآثار الجانبية (`send` و`agent`) من أجل
إعادة المحاولة بأمان؛ ويحتفظ الخادم بذاكرة تخزين مؤقت قصيرة العمر لإزالة التكرار.
- يجب أن تتضمن العقد `role: "node"` بالإضافة إلى caps/commands/permissions في `connect`.
## الاقتران + الثقة المحلية
- تتضمن جميع عملاء WS ‏(operators + nodes) **هوية جهاز** عند `connect`.
- تتطلب معرّفات الأجهزة الجديدة موافقة اقتران؛ ويصدر Gateway **رمز جهاز**
للاتصالات اللاحقة.
- يمكن الموافقة تلقائيًا على الاتصالات المحلية المباشرة عبر loopback للحفاظ على
سلاسة تجربة الاستخدام على المضيف نفسه.
- يمتلك OpenClaw أيضًا مسار اتصال ذاتي ضيقًا داخل الخلفية/الحاوية لتدفقات المساعد
الموثوقة ذات السر المشترك.
- لا تزال اتصالات tailnet وLAN، بما في ذلك روابط tailnet على المضيف نفسه، تتطلب
موافقة اقتران صريحة.
- يجب أن توقّع جميع الاتصالات قيمة nonce ‏`connect.challenge`.
- تربط حمولة التوقيع `v3` أيضًا `platform` + `deviceFamily`؛ ويثبّت gateway البيانات الوصفية المقترنة عند إعادة الاتصال ويتطلب اقتران إصلاح عند تغيّر البيانات الوصفية.
- لا تزال الاتصالات **غير المحلية** تتطلب موافقة صريحة.
- لا تزال مصادقة Gateway ‏(`gateway.auth.*`) تنطبق على **كل** الاتصالات، المحلية أو
البعيدة.
التفاصيل: [بروتوكول Gateway](/gateway/protocol)، [الاقتران](/channels/pairing)،
[الأمان](/gateway/security).
## كتابة أنواع البروتوكول وتوليد الشيفرة
- تعرّف مخططات TypeBox البروتوكول.
- يتم توليد JSON Schema من هذه المخططات.
- يتم توليد نماذج Swift من JSON Schema.
## الوصول البعيد
- المفضل: Tailscale أو VPN.
- البديل: نفق SSH
```bash
ssh -N -L 18789:127.0.0.1:18789 user@host
```
- تنطبق المصافحة نفسها + رمز المصادقة نفسه عبر النفق.
- يمكن تمكين TLS + التثبيت الاختياري لـ WS في الإعدادات البعيدة.
## لمحة تشغيلية
- البدء: `openclaw gateway` ‏(في الواجهة الأمامية، مع تسجيل السجلات إلى stdout).
- الصحة: `health` عبر WS ‏(ومضمنة أيضًا في `hello-ok`).
- الإشراف: launchd/systemd لإعادة التشغيل التلقائي.
## الثوابت
- يتحكم Gateway واحد فقط في جلسة Baileys واحدة لكل مضيف.
- المصافحة إلزامية؛ وأي إطار أول غير JSON أو غير `connect` يؤدي إلى إغلاق صارم.
- لا تتم إعادة تشغيل الأحداث؛ ويجب على العملاء إعادة التحديث عند وجود فجوات.
## ذو صلة
- [حلقة الوكيل](/concepts/agent-loop) — دورة تنفيذ الوكيل بالتفصيل
- [بروتوكول Gateway](/gateway/protocol) — عقد بروتوكول WebSocket
- [الطابور](/concepts/queue) — طابور الأوامر والتزامن
- [الأمان](/gateway/security) — نموذج الثقة والتقوية

Some files were not shown because too many files have changed in this diff Show More