Matrix - قناة دردشة

Matrix هو بروتوكول مراسلة مفتوح ولامركزي. يتصل OpenClaw كمستخدم Matrix على أي homeserver، لذا تحتاج إلى حساب Matrix للبوت. بمجرد تسجيل الدخول، يمكنك إرسال رسالة مباشرة للبوت أو دعوته إلى الغرف (مجموعات Matrix).

مكون إضافي مطلوب

Matrix يأتي كمكون إضافي وليس مجمعاً مع التثبيت الأساسي.

التثبيت عبر CLI (سجل npm):

openclaw plugins install @openclaw/matrix

التثبيت المحلي (عند التشغيل من مستودع git):

openclaw plugins install ./extensions/matrix

الإعداد

1. تثبيت مكون Matrix الإضافي:

   openclaw plugins install @openclaw/matrix

2. إنشاء حساب Matrix على homeserver:

   تصفح خيارات الاستضافة في matrix.org/ecosystem/hosting/

   أو استضافته بنفسك.

3. الحصول على access token لحساب البوت:

   استخدم Matrix login API مع curl في home server الخاص بك:

   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 بـ homeserver URL الخاص بك.

4. تكوين بيانات الاعتماد:

   Env: MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN (أو MATRIX_USER_ID + MATRIX_PASSWORD)

   أو config: channels.matrix.*

5. إعادة تشغيل Gateway (أو إنهاء الإعداد).
6. ابدأ رسالة مباشرة مع البوت أو ادعُه إلى غرفة من أي عميل Matrix (Element، Beeper، إلخ).

التكوين البسيط (access token، معرف المستخدم يتم جلبه تلقائياً)

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

تكوين E2EE (التشفير من طرف إلى طرف ممكّن)

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

التشفير (E2EE)

التشفير من طرف إلى طرف مدعوم عبر Rust crypto SDK.

قم بالتمكين باستخدام channels.matrix.encryption: true:

• إذا تم تحميل وحدة التشفير، يتم فك تشفير الغرف المشفرة تلقائياً.
• يتم تشفير الوسائط الصادرة عند الإرسال إلى الغرف المشفرة.
• عند الاتصال الأول، يطلب OpenClaw التحقق من الجهاز من جلساتك الأخرى.
• تحقق من الجهاز في عميل Matrix آخر (Element، إلخ) لتمكين مشاركة المفاتيح.
• إذا لم يمكن تحميل وحدة التشفير، يتم تعطيل E2EE ولن يتم فك تشفير الغرف المشفرة؛ OpenClaw يسجل تحذيراً.

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

• الردود تعود دائماً إلى 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.groupPolicy = "allowlist" (مغلق بالإشارة).

قائمة بيضاء للغرف مع 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 يحد من المرسلين الذين يمكنهم تفعيل البوت في الغرف.
• القوائم البيضاء للمستخدمين لكل غرفة يمكن أن تحد بشكل أكبر من المرسلين داخل غرفة معينة.

المواضيع

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

القدرات