​

23. Matrix (plagin)

24. Matrix — ochiq, markazlashtirilmagan xabar almashish protokoli. 25. OpenClaw Matrix foydalanuvchisi sifatida istalgan homeserverda ulanadi, shuning uchun bot uchun Matrix hisobi kerak. 26. Tizimga kirgach, botga bevosita DM yuborishingiz yoki uni xonalarga (Matrix “guruhlar”) taklif qilishingiz mumkin. 27. Beeper ham yaroqli mijoz variantidir, ammo u E2EE yoqilgan bo‘lishini talab qiladi.
25. Holat: plagin orqali qo‘llab-quvvatlanadi (@vector-im/matrix-bot-sdk). 29. To‘g‘ridan-to‘g‘ri xabarlar, xonalar, mavzular (threads), media, reaksiyalar, so‘rovlar (yuborish + poll-start matn sifatida), joylashuv va E2EE (kriptografik qo‘llab-quvvatlash bilan).

​

30. Plagin talab qilinadi

31. Matrix plagin sifatida yetkazib beriladi va asosiy o‘rnatmaga kiritilmagan.
32. CLI orqali o‘rnating (npm registri):

35. openclaw plugins install ./extensions/matrix

34. Lokal checkout (git repodan ishga tushirilganda):

35. openclaw plugins install ./extensions/matrix

36. Agar konfiguratsiya/onboarding vaqtida Matrix’ni tanlasangiz va git checkout aniqlansa, OpenClaw lokal o‘rnatish yo‘lini avtomatik taklif qiladi.
37. Tafsilotlar: Plugins

​

38. Sozlash

1. 39. Matrix plaginini o‘rnating:
   • 40. npm’dan: openclaw plugins install @openclaw/matrix
   • 41. Lokal checkout’dan: openclaw plugins install ./extensions/matrix
2. 42. Homeserverda Matrix hisobini yarating:
   • 43. Hosting variantlarini ko‘rib chiqing: https://matrix.org/ecosystem/hosting/
   • 44. Yoki uni o‘zingiz joylashtiring.
3. 45. Bot hisobi uchun access token oling:
   • 46. O‘z homeserveringizda curl orqali Matrix login API’dan foydalaning:
   47. 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"
   }'
   
   • 48. matrix.example.org ni homeserver URL’ingiz bilan almashtiring.
   • 49. Yoki channels.matrix.userId + channels.matrix.password ni sozlang: OpenClaw xuddi shu login endpoint’ini chaqiradi, access token’ni ~/.openclaw/credentials/matrix/credentials.json ga saqlaydi va keyingi ishga tushirishda undan qayta foydalanadi.
4. 50. Hisob ma’lumotlarini sozlash:
   • Env: MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN (or MATRIX_USER_ID + MATRIX_PASSWORD)
   • Or config: channels.matrix.*
   • If both are set, config takes precedence.
   • With access token: user ID is fetched automatically via /whoami.
   • When set, channels.matrix.userId should be the full Matrix ID (example: @bot:example.org).
5. Restart the gateway (or finish onboarding).
6. Start a DM with the bot or invite it to a room from any Matrix client (Element, Beeper, etc.; see https://matrix.org/ecosystem/clients/). Beeper requires E2EE, so set channels.matrix.encryption: true and verify the device.

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

​

Encryption (E2EE)

• If the crypto module loads, encrypted rooms are decrypted automatically.
• Outbound media is encrypted when sending to encrypted rooms.
• On first connection, OpenClaw requests device verification from your other sessions.
• Verify the device in another Matrix client (Element, etc.) to enable key sharing.
• If the crypto module cannot be loaded, E2EE is disabled and encrypted rooms will not decrypt; OpenClaw logs a warning.
• If you see missing crypto module errors (for example, @matrix-org/matrix-sdk-crypto-nodejs-*), allow build scripts for @matrix-org/matrix-sdk-crypto-nodejs and run pnpm rebuild @matrix-org/matrix-sdk-crypto-nodejs or fetch the binary with node node_modules/@matrix-org/matrix-sdk-crypto-nodejs/download-lib.js.

​

Ko‘p akkauntli rejim

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

• Akkauntni ishga tushirish ketma-ket bajariladi, bu bir vaqtning o‘zida modul importlari bilan bog‘liq race conditionlarning oldini oladi.
• Muhit o‘zgaruvchilari (MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN va boshqalar) faqat default akkauntga qo‘llaniladi.
• Asosiy kanal sozlamalari (DM policy, group policy, mention gating va boshqalar) har bir akkaunt uchun alohida bekor qilinmagan bo‘lsa, barcha akkauntlarga qo‘llaniladi.
• Har bir akkauntni turli agentga yo‘naltirish uchun bindings[].match.accountIddan foydalaning.
• Kripto holati har bir akkaunt + access token bo‘yicha saqlanadi (har bir akkaunt uchun alohida kalit saqlash joyi).

​

Routing model

• Replies always go back to Matrix.
• DMs share the agent’s main session; rooms map to group sessions.

​

Access control (DMs)

• Default: channels.matrix.dm.policy = "pairing". Unknown senders get a pairing code.
• Approve via:
  • openclaw pairing list matrix
  • openclaw pairing approve matrix <CODE>
• Public DMs: channels.matrix.dm.policy="open" plus channels.matrix.dm.allowFrom=["*"].
• channels.matrix.dm.allowFrom accepts full Matrix user IDs (example: @user:server). The wizard resolves display names to user IDs when directory search finds a single exact match.
• Display name yoki faqat localpart’dan (masalan: "Alice" yoki "alice") foydalanmang. Ular noaniq hisoblanadi va allowlist moslashtirishida e’tiborga olinmaydi. To‘liq @user:server IDlaridan foydalaning.

​

Rooms (groups)

• Default: channels.matrix.groupPolicy = "allowlist" (mention-gated). Use channels.defaults.groupPolicy to override the default when unset.
• Allowlist rooms with channels.matrix.groups (room IDs or aliases; names are resolved to IDs when directory search finds a single exact match):

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

• requireMention: false enables auto-reply in that room.
• groups."*" can set defaults for mention gating across rooms.
• groupAllowFrom restricts which senders can trigger the bot in rooms (full Matrix user IDs).
• Per-room users allowlists can further restrict senders inside a specific room (use full Matrix user IDs).
• The configure wizard prompts for room allowlists (room IDs, aliases, or names) and resolves names only on an exact, unique match.
• 1. Ishga tushishda OpenClaw allowlistlardagi xona/foydalanuvchi nomlarini IDlarga moslaydi va moslikni logga yozadi; aniqlanmagan yozuvlar allowlist moslashtirishida e’tiborga olinmaydi.
• 2. Takliflar odatda avtomatik qo‘shiladi; channels.matrix.autoJoin va channels.matrix.autoJoinAllowlist orqali boshqariladi.
• 3. Hech qanday xonaga ruxsat bermaslik uchun channels.matrix.groupPolicy: "disabled" qilib qo‘ying (yoki allowlistni bo‘sh qoldiring).
• 4. Meros kalit: channels.matrix.rooms (groups bilan bir xil tuzilma).

​

Threads

• Reply threading is supported.
• 7. channels.matrix.threadReplies javoblar tredlarda qolishini boshqaradi:
  • off, inbound (default), always
• channels.matrix.replyToMode controls reply-to metadata when not replying in a thread:
  • 10. off (standart), first, all

​

11. Imkoniyatlar

​

32. Nosozliklarni bartaraf etish

33. Avval ushbu ketma-ketlikni ishga tushiring:

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

35. So‘ng zarur bo‘lsa DM juftlash holatini tasdiqlang:

36. openclaw pairing list matrix

37. Keng tarqalgan xatolar:

• 38. Tizimga kirilgan, ammo xona xabarlari e’tiborsiz: xona groupPolicy yoki xona allowlisti tomonidan bloklangan.
• 39. DMlar e’tiborsiz: channels.matrix.dm.policy="pairing" bo‘lganda jo‘natuvchi tasdiqlanishni kutmoqda.
• 40. Shifrlangan xonalar ishlamaydi: kripto qo‘llab-quvvatlashi yoki shifrlash sozlamalari mos kelmaydi.

​

42. Konfiguratsiya ma’lumotnomasi (Matrix)

44. Provayder parametrlari:

• 45. channels.matrix.enabled: kanal ishga tushishini yoqish/o‘chirish.
• 46. channels.matrix.homeserver: homeserver URL manzili.
• 47. channels.matrix.userId: Matrix foydalanuvchi IDsi (access token bilan ixtiyoriy).
• channels.matrix.accessToken: access token.
• 49. channels.matrix.password: tizimga kirish paroli (token saqlanadi).
• 50. channels.matrix.deviceName: qurilma ko‘rinadigan nomi.
• channels.matrix.encryption: enable E2EE (default: false).
• channels.matrix.initialSyncLimit: initial sync limit.
• channels.matrix.threadReplies: off | inbound | always (default: inbound).
• channels.matrix.textChunkLimit: outbound text chunk size (chars).
• channels.matrix.chunkMode: length (default) or newline to split on blank lines (paragraph boundaries) before length chunking.
• channels.matrix.dm.policy: pairing | allowlist | open | disabled (default: pairing).
• channels.matrix.dm.allowFrom: DM allowlist (full Matrix user IDs). open requires "*". The wizard resolves names to IDs when possible.
• channels.matrix.groupPolicy: allowlist | open | disabled (default: allowlist).
• channels.matrix.groupAllowFrom: allowlisted senders for group messages (full Matrix user IDs).
• channels.matrix.allowlistOnly: force allowlist rules for DMs + rooms.
• channels.matrix.groups: group allowlist + per-room settings map.
• channels.matrix.rooms: legacy group allowlist/config.
• channels.matrix.replyToMode: reply-to mode for threads/tags.
• channels.matrix.mediaMaxMb: inbound/outbound media cap (MB).
• channels.matrix.autoJoin: invite handling (always | allowlist | off, default: always).
• channels.matrix.autoJoinAllowlist: allowed room IDs/aliases for auto-join.
• channels.matrix.accounts: akkaunt ID bo‘yicha kalitlangan ko‘p akkauntli konfiguratsiya (har bir akkaunt yuqori darajadagi sozlamalardan meros oladi).
• channels.matrix.actions: per-action tool gating (reactions/messages/pins/memberInfo/channelInfo).