​

Matrix (إضافة)

​

الإضافة المطلوبة

openclaw plugins install @openclaw/matrix

openclaw plugins install ./extensions/matrix

​

الإعداد

1. تثبيت إضافة Matrix:
   • من npm: openclaw plugins install @openclaw/matrix
   • من نسخة محلية: openclaw plugins install ./extensions/matrix
2. إنشاء حساب Matrix على خادم منزلي:
   • تصفّح خيارات الاستضافة على https://matrix.org/ecosystem/hosting/
   • أو استضِفه بنفسك.
3. الحصول على رمز وصول لحساب البوت:
   • استخدم واجهة تسجيل الدخول في Matrix مع curl على خادمك المنزلي:
   curl --request POST \
     --url https://matrix.example.org/_matrix/client/v3/login \
     --header 'Content-Type: application/json' \
     --data '{
     "type": "m.login.password",
     "identifier": {
       "type": "m.id.user",
       "user": "your-user-name"
     },
     "password": "your-password"
   }'
   
   • استبدل matrix.example.org بعنوان خادمك المنزلي.
   • أو اضبط channels.matrix.userId + channels.matrix.password: يستدعي OpenClaw نقطة تسجيل الدخول نفسها، ويخزّن رمز الوصول في ~/.openclaw/credentials/matrix/credentials.json، ويعيد استخدامه عند التشغيل التالي.
4. تهيئة بيانات الاعتماد:
   • متغيرات البيئة: MATRIX_HOMESERVER، MATRIX_ACCESS_TOKEN (أو MATRIX_USER_ID + MATRIX_PASSWORD)
   • أو في التهيئة: channels.matrix.*
   • إذا تم تعيين التهيئة تكون لها الأسبقية.
   • عند استخدام رمز الوصول: يتم جلب معرّف المستخدم تلقائيًا عبر /whoami.
   • عند التعيين، يجب أن يكون channels.matrix.userId هو معرّف Matrix الكامل (مثال: @bot:example.org).
5. أعد تشغيل Gateway (أو أكمل التهيئة الأولية).
6. ابدأ رسالة مباشرة مع البوت أو ادعه إلى غرفة من أي عميل Matrix (Element، Beeper، إلخ؛ انظر https://matrix.org/ecosystem/clients/). يتطلب Beeper تفعيل E2EE، لذا اضبط channels.matrix.encryption: true وتحقق من الجهاز.

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_***",
      dm: { policy: "pairing" },
    },
  },
}

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_***",
      encryption: true,
      dm: { policy: "pairing" },
    },
  },
}

​

التشفير (E2EE)

• إذا تم تحميل وحدة التشفير، فسيتم فك تشفير الغرف المشفّرة تلقائيًا.
• تُشفَّر الوسائط الصادرة عند الإرسال إلى غرف مشفّرة.
• عند الاتصال الأول، يطلب OpenClaw التحقق من الجهاز من جلساتك الأخرى.
• تحقّق من الجهاز في عميل Matrix آخر (Element، إلخ) لتمكين مشاركة المفاتيح. لتمكين مشاركة المفتاح.
• إذا تعذّر تحميل وحدة التشفير، يتم تعطيل E2EE ولن يتم فك تشفير الغرف المشفّرة؛ ويسجّل OpenClaw تحذيرًا.
• إذا رأيت أخطاء وحدة تشفير مفقودة (على سبيل المثال، @matrix-org/matrix-sdk-crypto-nodejs-*)، فاسمح بنصوص البناء لـ @matrix-org/matrix-sdk-crypto-nodejs وشغّل pnpm rebuild @matrix-org/matrix-sdk-crypto-nodejs أو اجلب الثنائي باستخدام node node_modules/@matrix-org/matrix-sdk-crypto-nodejs/download-lib.js.

​

متعدد الحسابات

{
  channels: {
    matrix: {
      enabled: true,
      dm: { policy: "pairing" },
      accounts: {
        assistant: {
          name: "Main assistant",
          homeserver: "https://matrix.example.org",
          accessToken: "syt_assistant_***",
          encryption: true,
        },
        alerts: {
          name: "Alerts bot",
          homeserver: "https://matrix.example.org",
          accessToken: "syt_alerts_***",
          dm: { policy: "allowlist", allowFrom: ["@admin:example.org"] },
        },
      },
    },
  },
}

• يتم تسلسل بدء تشغيل الحساب لتجنب حالات التعارض الناتجة عن استيراد الوحدات بشكل متزامن.
• متغيرات البيئة (MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN, إلخ) تنطبق فقط على الحساب الافتراضي.
• إعدادات القناة الأساسية (سياسة الرسائل الخاصة، سياسة المجموعات، تقييد الإشارات، إلخ) تنطبق على جميع الحسابات ما لم يتم تجاوزها لكل حساب على حدة.
• استخدم bindings[].match.accountId لتوجيه كل حساب إلى وكيل مختلف.
• يتم تخزين حالة التشفير لكل حساب + access token (مخازن مفاتيح منفصلة لكل حساب).

​

نموذج التوجيه

• تعود الردود دائمًا إلى Matrix.
• تشارك الرسائل المباشرة جلسة الوكيل الرئيسية؛ بينما تُطابِق الغرف جلسات جماعية.

​

التحكم في الوصول (الرسائل المباشرة)

• الافتراضي: channels.matrix.dm.policy = "pairing". يحصل المرسلون غير المعروفين على رمز إقران.
• الموافقة عبر:
  • openclaw pairing list matrix
  • openclaw pairing approve matrix <CODE>
• الرسائل المباشرة العامة: channels.matrix.dm.policy="open" بالإضافة إلى channels.matrix.dm.allowFrom=["*"].
• يقبل channels.matrix.dm.allowFrom معرّفات مستخدم Matrix الكاملة (مثال: @user:server). يحلّ معالج الإعداد أسماء العرض إلى معرّفات مستخدم عندما يجد بحث الدليل تطابقًا واحدًا دقيقًا.
• لا تستخدم أسماء العرض أو الأجزاء المحلية المجردة (مثال: "Alice" أو "alice"). فهي غامضة ويتم تجاهلها عند مطابقة قائمة السماح. استخدم معرّفات @user:server الكاملة.

​

الغرف (المجموعات)

• الافتراضي: channels.matrix.groupPolicy = "allowlist" (مقيّد بالذكر). استخدم channels.defaults.groupPolicy لتجاوز الافتراضي عند عدم التعيين.
• اسمح بالغرف عبر قائمة السماح باستخدام channels.matrix.groups (معرّفات الغرف أو الأسماء المستعارة؛ تُحلّ الأسماء إلى معرّفات عندما يجد بحث الدليل تطابقًا واحدًا دقيقًا):

{
  channels: {
    matrix: {
      groupPolicy: "allowlist",
      groups: {
        "!roomId:example.org": { allow: true },
        "#alias:example.org": { allow: true },
      },
      groupAllowFrom: ["@owner:example.org"],
    },
  },
}

• يفعّل requireMention: false الردّ التلقائي في تلك الغرفة.
• يمكن لـ groups."*" تعيين افتراضيات لتقييد الذكر عبر الغرف.
• يقيّد groupAllowFrom المرسلين القادرين على تشغيل البوت في الغرف (معرّفات مستخدم Matrix الكاملة).
• يمكن لقوائم السماح الخاصة بكل غرفة users تقييد المرسلين داخل غرفة محددة بشكل إضافي (استخدم معرّفات مستخدم Matrix الكاملة).
• يطلب معالج الإعداد قوائم السماح للغرف (معرّفات الغرف أو الأسماء المستعارة أو الأسماء) ولا يحلّ الأسماء إلا عند تطابق فريد ودقيق.
• عند بدء التشغيل، يحلّ OpenClaw أسماء الغرف/المستخدمين في قوائم السماح إلى معرّفات ويسجّل المطابقة؛ ويتم تجاهل الإدخالات غير المحلولة عند مطابقة قائمة السماح.
• تتم الانضمامات التلقائية للدعوات افتراضيًا؛ تحكّم بها عبر channels.matrix.autoJoin و channels.matrix.autoJoinAllowlist.
• للسماح بعدم وجود غرف، اضبط channels.matrix.groupPolicy: "disabled" (أو اترك قائمة السماح فارغة).
• المفتاح القديم: channels.matrix.rooms (بالشكل نفسه لـ groups).

​

Threads

• دعم سلاسل الردود متوفر.
• يتحكم channels.matrix.threadReplies فيما إذا كانت الردود تبقى ضمن السلاسل:
  • off، inbound (الافتراضي)، always
• يتحكم channels.matrix.replyToMode ببيانات الردّ عند عدم الرد ضمن سلسلة:
  • off (الافتراضي)، first، all

​

الإمكانات

​

استكشاف الأخطاء وإصلاحها

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

openclaw pairing list matrix

• تم تسجيل الدخول لكن تُتجاهل رسائل الغرف: الغرفة محجوبة بواسطة groupPolicy أو قائمة السماح للغرف.
• تُتجاهل الرسائل المباشرة: المرسل بانتظار الموافقة عندما يكون channels.matrix.dm.policy="pairing".
• فشل الغرف المشفّرة: عدم توافق دعم التشفير أو إعدادات التشفير.

​

مرجع التهيئة (Matrix)

• channels.matrix.enabled: تمكين/تعطيل بدء القناة.
• channels.matrix.homeserver: عنوان خادم Matrix المنزلي.
• channels.matrix.userId: معرّف مستخدم Matrix (اختياري مع رمز الوصول).
• channels.matrix.accessToken: رمز الوصول.
• channels.matrix.password: كلمة مرور لتسجيل الدخول (يتم تخزين الرمز).
• channels.matrix.deviceName: اسم عرض الجهاز.
• channels.matrix.encryption: تمكين E2EE (الافتراضي: false).
• channels.matrix.initialSyncLimit: حدّ المزامنة الأولية.
• channels.matrix.threadReplies: off | inbound | always (الافتراضي: inbound).
• channels.matrix.textChunkLimit: حجم تجزئة النص الصادر (عدد الأحرف).
• channels.matrix.chunkMode: length (الافتراضي) أو newline للتقسيم عند الأسطر الفارغة (حدود الفقرات) قبل التقسيم حسب الطول.
• channels.matrix.dm.policy: pairing | allowlist | open | disabled (الافتراضي: pairing).
• channels.matrix.dm.allowFrom: قائمة السماح للرسائل المباشرة (معرّفات مستخدم Matrix الكاملة). يتطلب open وجود "*". يحلّ المعالج الأسماء إلى معرّفات عند الإمكان.
• channels.matrix.groupPolicy: allowlist | open | disabled (الافتراضي: allowlist).
• channels.matrix.groupAllowFrom: المرسلون المسموح لهم لرسائل المجموعات (معرّفات مستخدم Matrix الكاملة).
• channels.matrix.allowlistOnly: فرض قواعد قائمة السماح على الرسائل المباشرة + الغرف.
• channels.matrix.groups: قائمة سماح المجموعات + خريطة إعدادات لكل غرفة.
• channels.matrix.rooms: تهيئة/قائمة سماح قديمة للمجموعات.
• channels.matrix.replyToMode: وضع الردّ للسلاسل/الوسوم.
• channels.matrix.mediaMaxMb: حدّ الوسائط الواردة/الصادرة (ميغابايت).
• channels.matrix.autoJoin: التعامل مع الدعوات (always | allowlist | off، الافتراضي: always).
• channels.matrix.autoJoinAllowlist: معرّفات/أسماء الغرف المسموح بها للانضمام التلقائي.
• channels.matrix.accounts: تهيئة متعددة الحسابات مُعرَّفة بواسطة معرّف الحساب (يرث كل حساب إعدادات المستوى الأعلى).
• channels.matrix.actions: تقييد الأدوات لكل إجراء (reactions/messages/pins/memberInfo/channelInfo).