​

Matrix

​

Plugin المدمج

openclaw plugins install @openclaw/matrix

openclaw plugins install ./path/to/local/matrix-plugin

​

الإعداد

1. تأكد من أن Plugin Matrix متاح.
   • إصدارات OpenClaw المجمعة الحالية تتضمنه بالفعل.
   • يمكن للتثبيتات الأقدم/المخصصة إضافته يدويًا باستخدام الأوامر أعلاه.
2. أنشئ حساب Matrix على خادمك المنزلي.
3. هيّئ channels.matrix باستخدام أحد الخيارين:
   • homeserver + accessToken، أو
   • homeserver + userId + password.
4. أعد تشغيل Gateway.
5. ابدأ رسالة خاصة مع البوت أو قم بدعوته إلى غرفة.
   • دعوات Matrix الجديدة تعمل فقط عندما يسمح channels.matrix.autoJoin بذلك.

openclaw channels add
openclaw configure --section channels

• عنوان URL للخادم المنزلي
• طريقة المصادقة: رمز وصول أو كلمة مرور
• معرّف المستخدم (لمصادقة كلمة المرور فقط)
• اسم جهاز اختياري
• ما إذا كان يجب تمكين التشفير التام بين الطرفين (E2EE)
• ما إذا كان يجب تهيئة الوصول إلى الغرف والانضمام التلقائي للدعوات

• إذا كانت متغيرات بيئة مصادقة Matrix موجودة بالفعل ولم يكن لهذا الحساب مصادقة محفوظة بالفعل في الإعدادات، فسيعرض المعالج اختصارًا لمتغيرات البيئة للإبقاء على المصادقة في متغيرات البيئة.
• تُطبّع أسماء الحسابات إلى معرّف الحساب. على سبيل المثال، يتحول Ops Bot إلى ops-bot.
• تقبل إدخالات قائمة السماح للرسائل الخاصة @user:server مباشرةً؛ ولا تعمل الأسماء المعروضة إلا عندما يعثر البحث المباشر في الدليل على تطابق واحد دقيق.
• تقبل إدخالات قائمة السماح للغرف معرّفات الغرف والأسماء المستعارة مباشرةً. فضّل !room:server أو #alias:server؛ ويتم تجاهل الأسماء غير المحلولة أثناء التشغيل عند تحليل قائمة السماح.
• في وضع قائمة السماح للانضمام التلقائي للدعوات، استخدم فقط أهداف الدعوات الثابتة: !roomId:server أو #alias:server أو *. تُرفض أسماء الغرف العادية.
• لتحليل أسماء الغرف قبل الحفظ، استخدم openclaw channels resolve --channel matrix "Project Room".

{
  channels: {
    matrix: {
      autoJoin: "allowlist",
      autoJoinAllowlist: ["!ops:example.org", "#support:example.org"],
      groups: {
        "!ops:example.org": {
          requireMention: true,
        },
      },
    },
  },
}

{
  channels: {
    matrix: {
      autoJoin: "always",
    },
  },
}

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

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      userId: "@bot:example.org",
      password: "replace-me", // pragma: allowlist secret
      deviceName: "OpenClaw Gateway",
    },
  },
}

• MATRIX_HOMESERVER
• MATRIX_ACCESS_TOKEN
• MATRIX_USER_ID
• MATRIX_PASSWORD
• MATRIX_DEVICE_ID
• MATRIX_DEVICE_NAME

• 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

• MATRIX_OPS_HOMESERVER
• MATRIX_OPS_ACCESS_TOKEN

• MATRIX_OPS_X2D_BOT_HOMESERVER
• MATRIX_OPS_X2D_BOT_ACCESS_TOKEN

​

مثال على التهيئة

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_xxx",
      encryption: true,

      dm: {
        policy: "pairing",
        sessionScope: "per-room",
        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",
    },
  },
}

​

معاينات البث

{
  channels: {
    matrix: {
      streaming: "partial",
    },
  },
}

• streaming: "off" هو الإعداد الافتراضي. ينتظر OpenClaw الرد النهائي ويرسله مرة واحدة.
• streaming: "partial" ينشئ رسالة معاينة واحدة قابلة للتحرير لكتلة المساعد الحالية باستخدام رسائل Matrix النصية العادية. يحافظ ذلك على سلوك الإشعارات القديم في Matrix القائم على المعاينة أولًا، لذا قد ترسل التطبيقات القياسية إشعارًا عند أول نص معاينة متدفق بدلًا من الكتلة النهائية المكتملة.
• streaming: "quiet" ينشئ إشعار معاينة هادئًا واحدًا قابلًا للتحرير لكتلة المساعد الحالية. استخدم هذا فقط عندما تهيئ أيضًا قواعد دفع للمستلمين من أجل تعديلات المعاينات النهائية.
• يفعّل blockStreaming: true رسائل تقدم منفصلة في Matrix. وعند تمكين بث المعاينة، يحتفظ Matrix بالمسودة المباشرة للكتلة الحالية ويحافظ على الكتل المكتملة كرسائل منفصلة.
• عندما يكون بث المعاينة قيد التشغيل ويكون blockStreaming متوقفًا، يحرر Matrix المسودة المباشرة في مكانها ويثبت الحدث نفسه عند انتهاء الكتلة أو الدور.
• إذا لم تعد المعاينة تتسع في حدث Matrix واحد، يوقف OpenClaw بث المعاينة ويعود إلى التسليم النهائي العادي.
• لا تزال ردود الوسائط ترسل المرفقات بشكل عادي. وإذا لم يعد من الآمن إعادة استخدام معاينة قديمة، يقوم OpenClaw بحذفها قبل إرسال رد الوسائط النهائي.
• تكلف تعديلات المعاينة طلبات إضافية إلى Matrix API. اترك البث متوقفًا إذا كنت تريد السلوك الأكثر تحفظًا فيما يتعلق بحدود المعدل.

• يرسل blockStreaming: true كل كتلة مكتملة كرسالة Matrix عادية مُرسِلة للإشعارات.
• يرسل blockStreaming: false الرد النهائي المكتمل فقط كرسالة Matrix عادية مُرسِلة للإشعارات.

​

قواعد دفع مستضافة ذاتيًا للمعاينات الهادئة النهائية

• المستخدم المستلم = الشخص الذي يجب أن يتلقى الإشعار
• مستخدم البوت = حساب Matrix الخاص بـ OpenClaw الذي يرسل الرد
• استخدم رمز وصول المستخدم المستلم في استدعاءات API أدناه
• طابِق sender في قاعدة الدفع مع MXID الكامل لمستخدم البوت

1. هيّئ OpenClaw لاستخدام المعاينات الهادئة:

{
  channels: {
    matrix: {
      streaming: "quiet",
    },
  },
}

2. تأكد من أن حساب المستلم يتلقى بالفعل إشعارات دفع Matrix العادية. لا تعمل قواعد المعاينات الهادئة إلا إذا كان لدى هذا المستخدم بالفعل pushers/أجهزة عاملة.
3. احصل على رمز وصول المستخدم المستلم.
   • استخدم رمز المستخدم المتلقي، وليس رمز البوت.
   • عادةً ما تكون إعادة استخدام رمز جلسة عميل موجودة هي الأسهل.
   • إذا كنت بحاجة إلى إصدار رمز جديد، يمكنك تسجيل الدخول عبر Matrix Client-Server API القياسي:

curl -sS -X POST \
  "https://matrix.example.org/_matrix/client/v3/login" \
  -H "Content-Type: application/json" \
  --data '{
    "type": "m.login.password",
    "identifier": {
      "type": "m.id.user",
      "user": "@alice:example.org"
    },
    "password": "REDACTED"
  }'

4. تحقّق من أن حساب المستلم لديه بالفعل pushers:

curl -sS \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  "https://matrix.example.org/_matrix/client/v3/pushers"

{
  "com.openclaw.finalized_preview": true
}

5. أنشئ قاعدة دفع من نوع override لكل حساب مستلم يجب أن يتلقى هذه الإشعارات:

curl -sS -X PUT \
  "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
    "conditions": [
      { "kind": "event_match", "key": "type", "pattern": "m.room.message" },
      {
        "kind": "event_property_is",
        "key": "content.m\\.relates_to.rel_type",
        "value": "m.replace"
      },
      {
        "kind": "event_property_is",
        "key": "content.com\\.openclaw\\.finalized_preview",
        "value": true
      },
      { "kind": "event_match", "key": "sender", "pattern": "@bot:example.org" }
    ],
    "actions": [
      "notify",
      { "set_tweak": "sound", "value": "default" },
      { "set_tweak": "highlight", "value": false }
    ]
  }'

• https://matrix.example.org: عنوان URL الأساسي لخادمك المنزلي
• $USER_ACCESS_TOKEN: رمز وصول المستخدم المتلقي
• openclaw-finalized-preview-botname: معرّف قاعدة فريد لهذا البوت لهذا المستخدم المتلقي
• @bot:example.org: معرّف MXID لبوت Matrix الخاص بـ OpenClaw، وليس MXID الخاص بالمستخدم المتلقي

• تُفهرس قواعد الدفع بواسطة ruleId. تؤدي إعادة تشغيل PUT على معرّف القاعدة نفسه إلى تحديث تلك القاعدة فقط.
• إذا كان على مستخدم مستلم واحد تلقي إشعارات لعدة حسابات بوت Matrix خاصة بـ OpenClaw، فأنشئ قاعدة واحدة لكل بوت مع معرّف قاعدة فريد لكل تطابق sender.
• نمط بسيط لذلك هو openclaw-finalized-preview-<botname>، مثل openclaw-finalized-preview-ops أو openclaw-finalized-preview-support.

• صادِق باستخدام رمز المستخدم المستلم
• طابِق sender مع MXID الخاص ببوت OpenClaw

6. تحقّق من وجود القاعدة:

curl -sS \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname"

7. اختبر ردًا متدفقًا. في الوضع الهادئ، يجب أن تُظهر الغرفة مسودة معاينة هادئة، ويجب أن يرسل التعديل النهائي في المكان نفسه إشعارًا واحدًا عند انتهاء الكتلة أو الدور.

curl -sS -X DELETE \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname"

• أنشئ القاعدة باستخدام رمز وصول المستخدم المستلم، وليس رمز البوت.
• تُدرج قواعد override الجديدة المعرّفة من قبل المستخدم قبل قواعد المنع الافتراضية، لذلك لا حاجة إلى معلمة ترتيب إضافية.
• يؤثر هذا فقط على تعديلات المعاينة النصية فقط التي يمكن لـ OpenClaw إنهاؤها بأمان في المكان نفسه. أما بدائل الوسائط وبدائل المعاينات القديمة فتظل تستخدم تسليم Matrix العادي.
• إذا أظهر GET /_matrix/client/v3/pushers عدم وجود pushers، فهذا يعني أن المستخدم لا يملك بعد تسليم دفع Matrix عاملًا لهذا الحساب/الجهاز.

​

Synapse

• لا يلزم إجراء تغيير خاص في homeserver.yaml لإشعارات معاينة OpenClaw النهائية.
• إذا كان نشر Synapse لديك يرسل بالفعل إشعارات دفع Matrix العادية، فإن رمز المستخدم + استدعاء pushrules أعلاه هما خطوة الإعداد الأساسية.
• إذا كنت تشغّل Synapse خلف وكيل عكسي أو workers، فتأكد من أن /_matrix/client/.../pushrules/ يصل إلى Synapse بشكل صحيح.
• إذا كنت تشغّل Synapse workers، فتأكد من أن pushers تعمل بشكل سليم. تتم معالجة تسليم الدفع بواسطة العملية الرئيسية أو synapse.app.pusher / workers المهيأة للدفع.

​

Tuwunel

• لا يلزم أي إعداد خاص بـ Tuwunel لعلامة المعاينة النهائية نفسها.
• إذا كانت إشعارات Matrix العادية تعمل بالفعل لهذا المستخدم، فإن رمز المستخدم + استدعاء pushrules أعلاه هما خطوة الإعداد الأساسية.
• إذا بدا أن الإشعارات تختفي بينما يكون المستخدم نشطًا على جهاز آخر، فتحقق مما إذا كان suppress_push_when_active ممكّنًا. أضاف Tuwunel هذا الخيار في Tuwunel 1.4.2 بتاريخ 12 سبتمبر 2025، ويمكنه عمدًا منع إشعارات الدفع إلى الأجهزة الأخرى بينما يكون أحد الأجهزة نشطًا.

​

غرف بوت إلى بوت

{
  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 هذا”.

​

التشفير والتحقق

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

openclaw matrix verify status

openclaw matrix verify status --verbose

openclaw matrix verify status --include-recovery-key --json

openclaw matrix verify bootstrap

openclaw matrix verify bootstrap --verbose

openclaw matrix verify bootstrap --force-reset-cross-signing

openclaw matrix verify device "<your-recovery-key>"

openclaw matrix verify device "<your-recovery-key>" --verbose

openclaw matrix verify backup status

openclaw matrix verify backup status --verbose

openclaw matrix verify backup restore

openclaw matrix verify backup restore --verbose

openclaw matrix verify backup reset --yes

openclaw matrix verify status --account assistant
openclaw matrix verify backup restore --account assistant
openclaw matrix devices list --account assistant

​

ما معنى “تم التحقق”

• Locally trusted: هذا الجهاز موثوق من قبل العميل الحالي فقط
• Cross-signing verified: يفيد SDK بأن الجهاز متحقق منه عبر التوقيع المتبادل
• Signed by owner: الجهاز موقَّع بواسطة مفتاح التوقيع الذاتي الخاص بك

​

ما الذي يفعله bootstrap

• يهيئ التخزين السري، مع إعادة استخدام مفتاح استرداد موجود متى أمكن
• يهيئ التوقيع المتبادل ويرفع مفاتيح التوقيع المتبادل العامة الناقصة
• يحاول تعليم الجهاز الحالي وتوقيعه عبر التوقيع المتبادل
• ينشئ نسخة احتياطية جديدة لمفاتيح الغرف على الخادم إذا لم تكن موجودة بالفعل

​

خط أساس جديد للنسخ الاحتياطي

openclaw matrix verify backup reset --yes
openclaw matrix verify backup status --verbose
openclaw matrix verify status

​

سلوك بدء التشغيل

​

إشعارات التحقق

• إشعارات طلب التحقق
• إشعارات جاهزية التحقق (مع إرشادات صريحة “تحقق عبر الرموز التعبيرية”)
• إشعارات بدء التحقق واكتماله
• تفاصيل SAS (الرموز التعبيرية والأرقام العشرية) عند توفرها

​

نظافة الأجهزة

openclaw matrix devices list

openclaw matrix devices prune-stale

​

مخزن التشفير

​

إدارة الملف الشخصي

openclaw matrix profile set --name "OpenClaw Assistant"
openclaw matrix profile set --avatar-url https://cdn.example.org/avatar.png

​

سلاسل الرسائل

• يحافظ dm.sessionScope: "per-user" (الافتراضي) على توجيه الرسائل الخاصة في Matrix ضمن نطاق المرسل، بحيث يمكن لعدة غرف رسائل خاصة مشاركة جلسة واحدة عندما تُحل إلى النظير نفسه.
• يعزل dm.sessionScope: "per-room" كل غرفة رسائل خاصة في Matrix داخل مفتاح جلسة خاص بها مع الاستمرار في استخدام المصادقة العادية للرسائل الخاصة وفحوصات قائمة السماح.
• لا تزال روابط محادثات Matrix الصريحة تتغلب على dm.sessionScope، لذلك تحتفظ الغرف وسلاسل الرسائل المرتبطة بجلسة الهدف المختارة لها.
• يُبقي threadReplies: "off" الردود في المستوى الأعلى، ويُبقي الرسائل الواردة ضمن سلسلة الرسائل على جلسة الرسالة الأصلية.
• يرد threadReplies: "inbound" داخل سلسلة الرسائل فقط عندما تكون الرسالة الواردة موجودة بالفعل في تلك السلسلة.
• يُبقي threadReplies: "always" ردود الغرف داخل سلسلة رسائل جذرها الرسالة المُشغِّلة، ويوجه تلك المحادثة عبر الجلسة المطابقة ذات النطاق الخاص بسلسلة الرسائل بدءًا من أول رسالة مُشغِّلة.
• يتجاوز dm.threadReplies الإعداد الأعلى مستوى للرسائل الخاصة فقط. على سبيل المثال، يمكنك إبقاء سلاسل رسائل الغرف معزولة مع إبقاء الرسائل الخاصة مسطحة.
• تتضمن الرسائل الواردة ضمن سلاسل الرسائل رسالة جذر السلسلة كسياق إضافي للوكيل.
• ترث عمليات الإرسال عبر أداة الرسائل سلسلة رسائل Matrix الحالية تلقائيًا عندما يكون الهدف هو الغرفة نفسها، أو هدف مستخدم الرسائل الخاصة نفسه، ما لم يُوفَّر threadId صريح.
• لا يُفعَّل إعادة استخدام هدف مستخدم الرسائل الخاصة ضمن الجلسة نفسها إلا عندما تثبت بيانات تعريف الجلسة الحالية أنه النظير نفسه للرسائل الخاصة على حساب Matrix نفسه؛ وإلا يعود OpenClaw إلى التوجيه العادي ذي النطاق الخاص بالمستخدم.
• عندما يرى OpenClaw أن غرفة رسائل خاصة في Matrix تتعارض مع غرفة رسائل خاصة أخرى على جلسة Matrix DM المشتركة نفسها، فإنه ينشر m.notice لمرة واحدة في تلك الغرفة مع مخرج /focus عند تمكين روابط سلاسل الرسائل وتلميح dm.sessionScope.
• تُدعَم روابط سلاسل الرسائل أثناء التشغيل في 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

• شغّل /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 فرعية أو ربطها.

​

تهيئة ربط سلاسل الرسائل

• threadBindings.enabled
• threadBindings.idleHours
• threadBindings.maxAgeHours
• threadBindings.spawnSubagentSessions
• threadBindings.spawnAcpSessions

• عيّن threadBindings.spawnSubagentSessions: true للسماح لـ /focus في المستوى الأعلى بإنشاء سلاسل رسائل Matrix جديدة وربطها.
• عيّن threadBindings.spawnAcpSessions: true للسماح لـ /acp spawn --thread auto|here بربط جلسات ACP بسلاسل رسائل Matrix.

​

التفاعلات

• تخضع أدوات التفاعل الصادرة إلى channels["matrix"].actions.reactions.
• يضيف react تفاعلًا إلى حدث Matrix محدد.
• يعرض reactions ملخص التفاعلات الحالي لحدث Matrix محدد.
• يزيل emoji="" تفاعلات حساب البوت نفسه على ذلك الحدث.
• يزيل remove: true تفاعل الرمز التعبيري المحدد فقط من حساب البوت.

• channels["matrix"].accounts.<accountId>.ackReaction
• channels["matrix"].ackReaction
• messages.ackReaction
• الرجوع إلى الرمز التعبيري الخاص بهوية الوكيل

• 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 يعرضها كعمليات حذف redactions، وليس كإزالة مستقلة لـ m.reaction.

​

سياق السجل

• يتحكم channels.matrix.historyLimit في عدد رسائل الغرفة الأخيرة المضمّنة كـ InboundHistory عندما تؤدي رسالة غرفة Matrix إلى تشغيل الوكيل. ويعود إلى messages.groupChat.historyLimit؛ وإذا لم يكن أيٌّ منهما معيّنًا، تكون القيمة الفعالة الافتراضية 0. عيّن 0 للتعطيل.
• يكون سجل غرف Matrix خاصًا بالغرف فقط. وتواصل الرسائل الخاصة استخدام سجل الجلسة العادي.
• يكون سجل غرف Matrix خاصًا بالرسائل المعلّقة فقط: يضع OpenClaw رسائل الغرفة التي لم تُطلِق ردًا بعد في مخزن مؤقت، ثم يلتقط لقطة لتلك النافذة عند وصول ذكر أو مُشغِّل آخر.
• لا تُضمَّن رسالة التشغيل الحالية في InboundHistory؛ بل تبقى في متن الرسالة الواردة الرئيسي لذلك الدور.
• تعيد محاولات الحدث نفسه في Matrix استخدام لقطة السجل الأصلية بدلًا من الانجراف إلى رسائل غرف أحدث.

​

إظهار السياق

• contextVisibility: "all" هو الإعداد الافتراضي. يُحتفَظ بالسياق الإضافي كما تم استلامه.
• يرشّح contextVisibility: "allowlist" السياق الإضافي إلى المرسلين المسموح لهم بموجب فحوصات قائمة السماح النشطة للغرفة/المستخدم.
• يعمل contextVisibility: "allowlist_quote" مثل allowlist، لكنه يحتفظ مع ذلك برد مقتبس صريح واحد.

​

سياسة الرسائل الخاصة والغرف

{
  channels: {
    matrix: {
      dm: {
        policy: "allowlist",
        allowFrom: ["@admin:example.org"],
        threadReplies: "off",
      },
      groupPolicy: "allowlist",
      groupAllowFrom: ["@admin:example.org"],
      groups: {
        "!roomid:example.org": {
          requireMention: true,
        },
      },
    },
  },
}

openclaw pairing list matrix
openclaw pairing approve matrix <CODE>

​

إصلاح الغرفة المباشرة

openclaw matrix direct inspect --user-id @alice:example.org

openclaw matrix direct repair --user-id @alice:example.org

• يفضّل رسالة خاصة صارمة 1:1 مُعيّنة بالفعل في m.direct
• يعود إلى أي رسالة خاصة صارمة 1:1 منضم إليها حاليًا مع ذلك المستخدم
• ينشئ غرفة مباشرة جديدة ويعيد كتابة m.direct إذا لم توجد رسالة خاصة سليمة

​

موافقات exec

• 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

• يتحكم channels.matrix.execApprovals.* في وضع التوزيع الأصلي للرسائل الخاصة/القنوات لطلبات الموافقة في Matrix.
• تستخدم موافقات exec مجموعة الموافقين الخاصة بالتنفيذ من execApprovals.approvers أو channels.matrix.dm.allowFrom.
• تستخدم موافقات Plugin قائمة السماح للرسائل الخاصة في Matrix من channels.matrix.dm.allowFrom.
• تنطبق اختصارات التفاعل في Matrix وتحديثات الرسائل على موافقات exec وموافقات Plugin معًا.

• يرسل target: "dm" طلبات الموافقة إلى الرسائل الخاصة للموافقين
• يرسل target: "channel" الطلب مرة أخرى إلى غرفة أو رسالة Matrix الأصلية
• يرسل target: "both" إلى الرسائل الخاصة للموافقين وإلى غرفة أو رسالة Matrix الأصلية

• ✅ = السماح مرة واحدة
• ❌ = الرفض
• ♾️ = السماح دائمًا عندما يكون هذا القرار مسموحًا به بموجب سياسة exec الفعالة

• channels.matrix.accounts.<account>.execApprovals

​

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

{
  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",
          },
        },
      },
    },
  },
}

​

الخوادم المنزلية الخاصة/خوادم LAN

{
  channels: {
    matrix: {
      homeserver: "http://matrix-synapse:8008",
      network: {
        dangerouslyAllowPrivateNetwork: true,
      },
      accessToken: "syt_internal_xxx",
    },
  },
}

openclaw matrix account add \
  --account ops \
  --homeserver http://matrix-synapse:8008 \
  --allow-private-network \
  --access-token syt_ops_xxx

​

توجيه حركة Matrix عبر Proxy

{
  channels: {
    matrix: {
      homeserver: "https://matrix.example.org",
      accessToken: "syt_bot_xxx",
      proxy: "http://127.0.0.1:7890",
    },
  },
}

​

تحليل الهدف

• المستخدمون: @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 على ذلك الخادم المنزلي.
• تقبل عمليات البحث عن الغرف معرّفات الغرف والأسماء المستعارة الصريحة مباشرةً، ثم تعود إلى البحث في أسماء الغرف المنضم إليها لذلك الحساب.
• يكون البحث باسم الغرفة المنضم إليها على أساس أفضل جهد. وإذا تعذر تحليل اسم غرفة إلى معرّف أو اسم مستعار، فسيتم تجاهله أثناء التشغيل عند تحليل قائمة السماح.

​

مرجع التهيئة

• enabled: تمكين القناة أو تعطيلها.
• name: تسمية اختيارية للحساب.
• defaultAccount: معرّف الحساب المفضّل عند تهيئة عدة حسابات Matrix.
• homeserver: عنوان URL للخادم المنزلي، مثل https://matrix.example.org.
• network.dangerouslyAllowPrivateNetwork: السماح لهذا الحساب في Matrix بالاتصال بالخوادم المنزلية الخاصة/الداخلية. فعّل هذا عندما يُحل الخادم المنزلي إلى localhost أو عنوان IP لشبكة LAN/Tailscale أو مضيف داخلي مثل matrix-synapse.
• proxy: عنوان URL اختياري لـ HTTP(S) Proxy لحركة Matrix. ويمكن للحسابات المسماة تجاوز الإعداد الافتراضي الأعلى مستوى باستخدام proxy خاص بها.
• userId: معرّف مستخدم Matrix الكامل، مثل @bot:example.org.
• accessToken: رمز وصول للمصادقة المستندة إلى الرمز. القيم النصية الصريحة وقيم SecretRef مدعومة في channels.matrix.accessToken وchannels.matrix.accounts.<id>.accessToken عبر موفري env/file/exec. راجع إدارة الأسرار.
• password: كلمة مرور لتسجيل الدخول المستند إلى كلمة المرور. القيم النصية الصريحة وقيم SecretRef مدعومة.
• deviceId: معرّف جهاز Matrix صريح.
• deviceName: اسم عرض الجهاز لتسجيل الدخول بكلمة المرور.
• avatarUrl: عنوان URL المخزن للصورة الرمزية الذاتية لمزامنة الملف الشخصي وتحديثات profile set.
• initialSyncLimit: الحد الأقصى لعدد الأحداث التي يتم جلبها أثناء مزامنة بدء التشغيل.
• encryption: تمكين E2EE.
• allowlistOnly: عندما تكون true، تتم ترقية سياسة الغرف open إلى allowlist، وتُفرَض جميع سياسات الرسائل الخاصة النشطة باستثناء disabled (بما في ذلك pairing وopen) إلى allowlist. ولا يؤثر ذلك في سياسات disabled.
• allowBots: السماح بالرسائل من حسابات OpenClaw Matrix الأخرى المهيأة (true أو "mentions").
• groupPolicy: open أو allowlist أو disabled.
• contextVisibility: وضع إظهار سياق الغرفة الإضافي (all أو allowlist أو allowlist_quote).
• groupAllowFrom: قائمة سماح لمعرّفات المستخدمين لحركة الغرف. يجب أن تكون الإدخالات معرّفات مستخدمي Matrix كاملة؛ وتُتجاهل الأسماء غير المحلولة أثناء التشغيل.
• historyLimit: الحد الأقصى لرسائل الغرف المضمنة كسياق سجل للمجموعة. ويعود إلى messages.groupChat.historyLimit؛ وإذا لم يكن أيٌّ منهما معيّنًا، تكون القيمة الفعالة الافتراضية 0. عيّن 0 للتعطيل.
• replyToMode: off أو first أو all أو batched.
• markdown: تهيئة اختيارية لعرض Markdown لنص Matrix الصادر.
• streaming: off (الافتراضي) أو "partial" أو "quiet" أو true أو false. يفعّل "partial" وtrue تحديثات المسودات بنمط المعاينة أولًا باستخدام رسائل Matrix النصية العادية. ويستخدم "quiet" إشعارات معاينة غير مُرسِلة للإشعار لإعدادات push-rule المستضافة ذاتيًا. ويكافئ false القيمة "off".
• blockStreaming: يفعّل true رسائل تقدم منفصلة لكتل المساعد المكتملة أثناء نشاط بث معاينة المسودات.
• threadReplies: off أو inbound أو always.
• threadBindings: تجاوزات لكل قناة لتوجيه الجلسات المرتبطة بسلاسل الرسائل ودورة حياتها.
• startupVerification: وضع طلب التحقق الذاتي التلقائي عند بدء التشغيل (if-unverified أو off).
• startupVerificationCooldownHours: فترة التهدئة قبل إعادة محاولة طلبات التحقق التلقائي عند بدء التشغيل.
• textChunkLimit: حجم أجزاء الرسالة الصادرة بالأحرف (يُطبَّق عندما يكون chunkMode هو length).
• chunkMode: يقسّم length الرسائل حسب عدد الأحرف؛ ويقسّم newline عند حدود الأسطر.
• responsePrefix: سلسلة اختيارية تسبق جميع الردود الصادرة لهذه القناة.
• ackReaction: تجاوز اختياري لتفاعل الإقرار لهذه القناة/الحساب.
• ackReactionScope: تجاوز اختياري لنطاق تفاعل الإقرار (group-mentions أو group-all أو direct أو all أو none أو off).
• reactionNotifications: وضع إشعارات التفاعل الواردة (own أو off).
• mediaMaxMb: الحد الأقصى لحجم الوسائط بالميغابايت لعمليات الإرسال الصادرة ومعالجة الوسائط الواردة.
• autoJoin: سياسة الانضمام التلقائي للدعوات (always أو allowlist أو off). الافتراضي: off. وتنطبق على جميع دعوات Matrix، بما في ذلك الدعوات بأسلوب الرسائل الخاصة.
• autoJoinAllowlist: الغرف/الأسماء المستعارة المسموح بها عندما تكون autoJoin هي allowlist. وتُحل إدخالات الأسماء المستعارة إلى معرّفات غرف أثناء معالجة الدعوة؛ ولا يثق OpenClaw في حالة الاسم المستعار التي تدّعيها الغرفة المدعو إليها.
• dm: كتلة سياسة الرسائل الخاصة (enabled وpolicy وallowFrom وsessionScope وthreadReplies).
• dm.policy: يتحكم في الوصول إلى الرسائل الخاصة بعد انضمام OpenClaw إلى الغرفة وتصنيفها على أنها رسالة خاصة. ولا يغيّر ما إذا كانت الدعوة ستنضم تلقائيًا.
• dm.allowFrom: يجب أن تكون الإدخالات معرّفات مستخدمي Matrix كاملة ما لم تكن قد حللتها بالفعل عبر البحث المباشر في الدليل.
• dm.sessionScope: per-user (الافتراضي) أو per-room. استخدم per-room عندما تريد أن تحتفظ كل غرفة رسائل خاصة في 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).

​

ذو صلة

• نظرة عامة على القنوات — جميع القنوات المدعومة
• الإقران — مصادقة الرسائل الخاصة وتدفق الإقران
• المجموعات — سلوك دردشة المجموعات وتقييد الذكر
• توجيه القناة — توجيه الجلسات للرسائل
• الأمان — نموذج الوصول والتحصين