Matrix (plugin)

Matrix là một giao thức nhắn tin mở và phi tập trung. OpenClaw kết nối với vai trò là một user Matrix trên bất kỳ homeserver nào, nên các bạn cần tạo tài khoản Matrix cho bot. Sau khi đăng nhập, các bạn có thể DM trực tiếp với bot hoặc mời nó vào các room (hay “nhóm” trong Matrix). Beeper cũng là một client hợp lệ, nhưng nó yêu cầu bật E2EE.

Trạng thái: được hỗ trợ qua plugin (@vector-im/matrix-bot-sdk). Hỗ trợ tin nhắn trực tiếp, room, thread, media, reaction, poll (gửi + poll-start dạng text), vị trí, và E2EE (với crypto support).

Cần cài Plugin

Matrix được phân phối dưới dạng plugin và không đi kèm với bản cài đặt core.

Cài đặt qua CLI (npm registry):

openclaw plugins install @openclaw/matrix

Cài từ local checkout (khi chạy từ git repo):

openclaw plugins install ./extensions/matrix

Nếu các bạn chọn Matrix trong quá trình configure/onboarding và phát hiện git checkout, OpenClaw sẽ tự động đề xuất đường dẫn cài đặt local.

Chi tiết: Plugins

Thiết lập

1. Cài đặt Matrix plugin:

   • Từ npm: openclaw plugins install @openclaw/matrix
   • Từ local checkout: openclaw plugins install ./extensions/matrix

2. Tạo tài khoản Matrix trên một homeserver:

   • Xem các tùy chọn hosting tại https://matrix.org/ecosystem/hosting/
   • Hoặc tự host.

3. Lấy access token cho tài khoản bot:

   • Dùng Matrix login API với curl tại home server của các bạn:

   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"
   }'

   • Thay matrix.example.org bằng URL homeserver của các bạn.
   • Hoặc set channels.matrix.userId + channels.matrix.password: OpenClaw sẽ gọi cùng login endpoint đó, lưu access token vào ~/.openclaw/credentials/matrix/credentials.json, và dùng lại khi khởi động lần sau.

4. Cấu hình credentials:

   • Env: MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN (hoặc MATRIX_USER_ID + MATRIX_PASSWORD)
   • Hoặc config: channels.matrix.*
   • Nếu set cả hai, config sẽ được ưu tiên.
   • Với access token: user ID sẽ được lấy tự động qua /whoami.
   • Khi set, channels.matrix.userId phải là Matrix ID đầy đủ (ví dụ: @bot:example.org).

5. Khởi động lại Gateway (hoặc hoàn tất onboarding).

6. Bắt đầu DM với bot hoặc mời nó vào room từ bất kỳ Matrix client nào (Element, Beeper, v.v.; xem https://matrix.org/ecosystem/clients/). Beeper yêu cầu E2EE, nên set channels.matrix.encryption: true và verify device.

Config tối thiểu (access token, user ID tự động lấy):

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

Config E2EE (bật end-to-end encryption):

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

Mã hóa (E2EE)

Mã hóa end-to-end được hỗ trợ qua Rust crypto SDK.

Bật bằng channels.matrix.encryption: true:

• Nếu crypto module load được, các room được mã hóa sẽ tự động giải mã.
• Media gửi đi sẽ được mã hóa khi gửi vào room đã mã hóa.
• Khi kết nối lần đầu, OpenClaw sẽ yêu cầu device verification từ các session khác của các bạn.
• Verify device trong một Matrix client khác (Element, v.v.) để bật key sharing.
• Nếu crypto module không thể load, E2EE sẽ bị tắt và các room đã mã hóa sẽ không giải mã được; OpenClaw sẽ log cảnh báo.
• Nếu các bạn thấy lỗi thiếu crypto module (ví dụ: @matrix-org/matrix-sdk-crypto-nodejs-*), cho phép build scripts cho @matrix-org/matrix-sdk-crypto-nodejs và chạy pnpm rebuild @matrix-org/matrix-sdk-crypto-nodejs hoặc fetch binary bằng node node_modules/@matrix-org/matrix-sdk-crypto-nodejs/download-lib.js.

Crypto state được lưu theo account + access token trong ~/.openclaw/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/crypto/ (SQLite database). Sync state nằm cùng chỗ trong bot-storage.json. Nếu access token (device) thay đổi, một store mới sẽ được tạo và bot phải được verify lại cho các room đã mã hóa.

Device verification: Khi E2EE được bật, bot sẽ yêu cầu verification từ các session khác của các bạn khi khởi động. Mở Element (hoặc client khác) và chấp nhận yêu cầu verification để thiết lập trust. Sau khi verify, bot có thể giải mã tin nhắn trong các room đã mã hóa.

Mô hình Routing

• Các reply luôn quay về Matrix.
• DM dùng chung Session chính của Agent; các room map tới group session.

Kiểm soát truy cập (DM)

• Mặc định: channels.matrix.dm.policy = "pairing". Người gửi không xác định sẽ nhận pairing code.
• Phê duyệt qua:
  • openclaw pairing list matrix
  • openclaw pairing approve matrix <CODE>
• DM công khai: channels.matrix.dm.policy="open" cộng với channels.matrix.dm.allowFrom=["*"].
• channels.matrix.dm.allowFrom chấp nhận user ID hoặc display name. Wizard sẽ resolve display name thành user ID khi directory search khả dụng.

Room (nhóm)

• Mặc định: channels.matrix.groupPolicy = "allowlist" (mention-gated). Dùng channels.defaults.groupPolicy để override mặc định khi chưa set.
• Allowlist các room bằng channels.matrix.groups (room ID, alias, hoặc tên):

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

• requireMention: false bật auto-reply trong room đó.
• groups."*" có thể set mặc định cho mention gating trên các room.
• groupAllowFrom giới hạn người gửi nào có thể trigger bot trong room (tùy chọn).
• Allowlist users theo từng room có thể giới hạn thêm người gửi bên trong một room cụ thể.
• Configure wizard sẽ hỏi về room allowlist (room ID, alias, hoặc tên) và resolve tên khi có thể.
• Khi khởi động, OpenClaw resolve tên room/user trong allowlist thành ID và log mapping; các entry không resolve được sẽ giữ nguyên như đã nhập.
• Invite được auto-join mặc định; kiểm soát bằng channels.matrix.autoJoin và channels.matrix.autoJoinAllowlist.
• Để không cho phép room nào, set channels.matrix.groupPolicy: "disabled" (hoặc giữ allowlist rỗng).
• Key cũ: channels.matrix.rooms (cùng cấu trúc với groups).

Thread

• Reply threading được hỗ trợ.
• channels.matrix.threadReplies kiểm soát việc reply có ở trong thread không:
  • off, inbound (mặc định), always
• channels.matrix.replyToMode kiểm soát reply-to metadata khi không reply trong thread:
  • off (mặc định), first, all

Tính năng

Tham khảo cấu hình (Matrix)

Cấu hình đầy đủ: Configuration

Các tùy chọn Provider:

• channels.matrix.enabled: bật/tắt khởi động Channel.
• channels.matrix.homeserver: URL homeserver.
• channels.matrix.userId: Matrix user ID (tùy chọn với access token).
• channels.matrix.accessToken: access token.
• channels.matrix.password: password để login (token được lưu).
• channels.matrix.deviceName: tên hiển thị device.
• channels.matrix.encryption: bật E2EE (mặc định: false).
• channels.matrix.initialSyncLimit: giới hạn initial sync.
• channels.matrix.threadReplies: off | inbound | always (mặc định: inbound).
• channels.matrix.textChunkLimit: kích thước chunk text gửi đi (ký tự).
• channels.matrix.chunkMode: length (mặc định) hoặc newline để tách theo dòng trống (ranh giới đoạn văn) trước khi chunk theo độ dài.
• channels.matrix.dm.policy: pairing | allowlist | open | disabled (mặc định: pairing).
• channels.matrix.dm.allowFrom: DM allowlist (user ID hoặc display name). open yêu cầu "*". Wizard resolve tên thành ID khi có thể.
• channels.matrix.groupPolicy: allowlist | open | disabled (mặc định: allowlist).
• channels.matrix.groupAllowFrom: người gửi được allowlist cho tin nhắn nhóm.
• channels.matrix.allowlistOnly: bắt buộc quy tắc allowlist cho DM + room.
• channels.matrix.groups: group allowlist + map cài đặt theo room.
• channels.matrix.rooms: group allowlist/config cũ.
• channels.matrix.replyToMode: chế độ reply-to cho thread/tag.
• channels.matrix.mediaMaxMb: giới hạn media nhận/gửi (MB).
• channels.matrix.autoJoin: xử lý invite (always | allowlist | off, mặc định: always).
• channels.matrix.autoJoinAllowlist: room ID/alias được phép auto-join.
• channels.matrix.actions: gating tool theo action (reaction/message/pin/memberInfo/channelInfo).