​

Matrix (plugin)

​

Yêu cầu plugin

openclaw plugins install @openclaw/matrix

openclaw plugins install ./extensions/matrix

​

Thiết lập

1. Cài đặt plugin.
2. Tạo tài khoản Matrix trên máy chủ của bạn.
3. Cấu hình channels.matrix với:
   • homeserver + accessToken, hoặc
   • homeserver + userId + password.
4. Khởi động lại gateway.
5. Bắt đầu một DM với bot hoặc mời bot vào phòng.

openclaw channels add
openclaw configure --section channels

• URL của homeserver
• Phương thức xác thực: access token hoặc password
• user ID chỉ khi chọn xác thực bằng password
• Tên thiết bị tùy chọn
• Có bật E2EE hay không
• Có cấu hình truy cập phòng Matrix ngay không

• Nếu biến môi trường xác thực Matrix đã tồn tại cho tài khoản đã chọn và tài khoản đó chưa có xác thực lưu trong cấu hình, wizard sẽ cung cấp một lối tắt qua biến môi trường và chỉ ghi enabled: true cho tài khoản đó.
• Khi thêm tài khoản Matrix khác một cách tương tác, tên tài khoản nhập vào sẽ được chuẩn hóa thành ID tài khoản được sử dụng trong cấu hình và biến môi trường. Ví dụ, Ops Bot trở thành ops-bot.
• Các lời nhắc danh sách cho phép DM chấp nhận giá trị đầy đủ @user:server ngay lập tức. Tên hiển thị chỉ hoạt động khi tra cứu thư mục trực tiếp tìm thấy một kết quả khớp chính xác; nếu không, wizard sẽ yêu cầu thử lại với ID Matrix đầy đủ.
• Các lời nhắc danh sách cho phép phòng chấp nhận ID phòng và bí danh trực tiếp. Chúng cũng có thể giải quyết tên phòng đã tham gia trực tiếp, nhưng các tên không được giải quyết chỉ được giữ lại như đã nhập trong quá trình thiết lập và bị bỏ qua sau đó bởi quá trình giải quyết danh sách cho phép khi chạy. Ưu tiên !room:server hoặc #alias:server.
• Danh tính phòng/phiên khi chạy sử dụng ID phòng Matrix ổn định. Các bí danh được khai báo trong phòng chỉ được sử dụng làm đầu vào tra cứu, không phải là khóa phiên dài hạn hoặc danh tính nhóm ổn định.
• Để giải quyết tên phòng trước khi lưu chúng, sử dụng openclaw channels resolve --channel matrix "Project Room".

{
  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_BOT_HOMESERVER
• MATRIX_OPS_BOT_ACCESS_TOKEN

​

Ví dụ cấu hình

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

      dm: {
        policy: "pairing",
      },

      groupPolicy: "allowlist",
      groupAllowFrom: ["@admin:example.org"],
      groups: {
        "!roomid:example.org": {
          requireMention: true,
        },
      },

      autoJoin: "allowlist",
      autoJoinAllowlist: ["!roomid:example.org"],
      threadReplies: "inbound",
      replyToMode: "off",
    },
  },
}

​

Thiết lập E2EE

​

Phòng bot-to-bot

{
  channels: {
    matrix: {
      allowBots: "mentions", // true | "mentions"
      groups: {
        "!roomid:example.org": {
          requireMention: true,
        },
      },
    },
  },
}

• allowBots: true chấp nhận tin nhắn từ các tài khoản bot Matrix khác trong các phòng và DM được phép.
• allowBots: "mentions" chỉ chấp nhận những tin nhắn đó khi chúng đề cập rõ ràng đến bot này trong phòng. DM vẫn được phép.
• groups.<room>.allowBots ghi đè cài đặt cấp tài khoản cho một phòng.
• OpenClaw vẫn bỏ qua các tin nhắn từ cùng một ID người dùng Matrix để tránh vòng lặp tự trả lời.
• Matrix không cung cấp cờ bot gốc ở đây; OpenClaw coi “do bot tạo ra” là “được gửi bởi một tài khoản Matrix khác được cấu hình trên gateway OpenClaw này”.

{
  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

​

Ý nghĩa của “đã xác minh”

• Locally trusted: thiết bị này chỉ được tin cậy bởi client hiện tại
• Cross-signing verified: SDK báo cáo thiết bị đã được xác minh thông qua ký chéo
• Signed by owner: thiết bị được ký bởi khóa tự ký của bạn

​

Những gì khởi tạo làm

• khởi tạo lưu trữ bí mật, tái sử dụng khóa khôi phục hiện có khi có thể
• khởi tạo ký chéo và tải lên các khóa ký chéo công khai bị thiếu
• cố gắng đánh dấu và ký chéo thiết bị hiện tại
• tạo một bản sao lưu khóa phòng phía máy chủ mới nếu chưa có

​

Cơ sở sao lưu mới

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

​

Hành vi khởi động

• OpenClaw tự động tái sử dụng cùng tài khoản Matrix, access token và danh tính thiết bị khi có thể.
• Trước khi bất kỳ thay đổi di chuyển Matrix nào có thể thực hiện được, OpenClaw tạo hoặc tái sử dụng một bản sao lưu dưới ~/Backups/openclaw-migrations/.
• Nếu bạn sử dụng nhiều tài khoản Matrix, hãy đặt channels.matrix.defaultAccount trước khi nâng cấp từ bố cục lưu trữ phẳng cũ để OpenClaw biết tài khoản nào nên nhận trạng thái kế thừa chia sẻ đó.
• Nếu plugin trước đó lưu trữ một khóa giải mã sao lưu khóa phòng Matrix cục bộ, khởi động hoặc openclaw doctor --fix sẽ nhập nó vào luồng khóa khôi phục mới tự động.
• Nếu access token Matrix thay đổi sau khi di chuyển đã được chuẩn bị, khởi động bây giờ quét các gốc lưu trữ hash token anh em cho trạng thái khôi phục kế thừa đang chờ trước khi từ bỏ trạng thái Matrix trống.
• Nếu access token Matrix thay đổi sau đó cho cùng tài khoản, máy chủ, và người dùng, OpenClaw bây giờ ưu tiên tái sử dụng gốc lưu trữ hiện có hoàn chỉnh nhất thay vì bắt đầu từ một thư mục trạng thái Matrix trống.
• Vào lần khởi động gateway tiếp theo, các khóa phòng đã sao lưu được khôi phục tự động vào cửa hàng mã hóa mới.
• Nếu plugin cũ có các khóa phòng chỉ cục bộ chưa bao giờ được sao lưu, OpenClaw sẽ cảnh báo rõ ràng. Những khóa đó không thể được xuất tự động từ cửa hàng mã hóa rust trước đó, vì vậy một số lịch sử mã hóa cũ có thể vẫn không thể truy cập được cho đến khi được khôi phục thủ công.
• Xem Di chuyển Matrix để biết luồng nâng cấp đầy đủ, giới hạn, lệnh khôi phục và các thông báo di chuyển phổ biến.

​

Mô hình cửa hàng mã hóa Node

• sử dụng fake-indexeddb làm API IndexedDB giả lập mà SDK mong đợi
• khôi phục nội dung IndexedDB mã hóa Rust từ crypto-idb-snapshot.json trước initRustCrypto
• lưu trữ nội dung IndexedDB đã cập nhật trở lại crypto-idb-snapshot.json sau khi khởi tạo và trong runtime

• thêm hỗ trợ SecretRef cho vật liệu khóa Matrix bền vững để khóa khôi phục và các bí mật mã hóa cửa hàng liên quan có thể được lấy từ các nhà cung cấp bí mật OpenClaw thay vì chỉ từ các tệp cục bộ

​

Thông báo xác minh tự động

• thông báo yêu cầu xác minh
• thông báo sẵn sàng xác minh (với hướng dẫn “Xác minh bằng emoji” rõ ràng)
• thông báo bắt đầu và hoàn thành xác minh
• chi tiết SAS (emoji và số thập phân) khi có sẵn

​

Vệ sinh thiết bị

openclaw matrix devices list

openclaw matrix devices prune-stale

​

Sửa chữa phòng trực tiếp

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

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

• nó ưu tiên một DM 1:1 nghiêm ngặt đã được ánh xạ trong m.direct
• nếu không, nó quay lại bất kỳ DM 1:1 nghiêm ngặt nào hiện đang tham gia với người dùng đó
• nếu không có DM nào khỏe mạnh tồn tại, nó tạo một phòng trực tiếp mới và viết lại m.direct để chỉ vào nó

​

Luồng

• threadReplies: "off" giữ các trả lời ở cấp cao nhất.
• threadReplies: "inbound" trả lời trong một luồng chỉ khi tin nhắn đến đã ở trong luồng đó.
• threadReplies: "always" giữ các trả lời phòng trong một luồng bắt nguồn từ tin nhắn kích hoạt.
• Các tin nhắn luồng đến bao gồm tin nhắn gốc của luồng làm ngữ cảnh agent bổ sung.
• Gửi công cụ tin nhắn bây giờ tự động kế thừa luồng Matrix hiện tại khi mục tiêu là cùng một phòng, hoặc cùng một mục tiêu người dùng DM, trừ khi một threadId rõ ràng được cung cấp.
• Các ràng buộc luồng runtime được hỗ trợ cho Matrix. /focus, /unfocus, /agents, /session idle, /session max-age, và /acp spawn ràng buộc luồng bây giờ hoạt động trong các phòng và DM Matrix.
• /focus phòng/DM Matrix cấp cao nhất tạo một luồng Matrix mới và ràng buộc nó với phiên mục tiêu khi threadBindings.spawnSubagentSessions=true.
• Chạy /focus hoặc /acp spawn --thread here bên trong một luồng Matrix hiện có ràng buộc luồng hiện tại thay thế.

​

Cấu hình Ràng buộc Luồng

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

• Đặt threadBindings.spawnSubagentSessions: true để cho phép /focus cấp cao nhất tạo và ràng buộc các luồng Matrix mới.
• Đặt threadBindings.spawnAcpSessions: true để cho phép /acp spawn --thread auto|here ràng buộc các phiên ACP với các luồng Matrix.

​

Phản ứng

• Công cụ phản ứng ra ngoài được kiểm soát bởi channels["matrix"].actions.reactions.
• react thêm một phản ứng vào một sự kiện Matrix cụ thể.
• reactions liệt kê tóm tắt phản ứng hiện tại cho một sự kiện Matrix cụ thể.
• emoji="" xóa các phản ứng của tài khoản bot trên sự kiện đó.
• remove: true chỉ xóa phản ứng emoji được chỉ định từ tài khoản bot.

• channels["matrix"].accounts.<accountId>.ackReaction
• channels["matrix"].ackReaction
• messages.ackReaction
• dự phòng emoji danh tính agent

• channels["matrix"].accounts.<accountId>.ackReactionScope
• channels["matrix"].ackReactionScope
• messages.ackReactionScope

• channels["matrix"].accounts.<accountId>.reactionNotifications
• channels["matrix"].reactionNotifications
• mặc định: own

• reactionNotifications: "own" chuyển tiếp các sự kiện m.reaction được thêm vào khi chúng nhắm mục tiêu các tin nhắn Matrix do bot tạo ra.
• reactionNotifications: "off" tắt các sự kiện hệ thống phản ứng.
• Việc xóa phản ứng vẫn chưa được tổng hợp thành các sự kiện hệ thống vì Matrix hiển thị chúng dưới dạng các chỉnh sửa, không phải là các xóa m.reaction độc lập.

​

Ví dụ về chính sách DM và phòng

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

openclaw pairing list matrix
openclaw pairing approve matrix <CODE>

​

Ví dụ nhiều tài khoản

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

​

Máy chủ riêng/LAN

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

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

​

Giải quyết mục tiêu

• Người dùng: @user:server, user:@user:server, hoặc matrix:user:@user:server
• Phòng: !room:server, room:!room:server, hoặc matrix:room:!room:server
• Bí danh: #alias:server, channel:#alias:server, hoặc matrix:channel:#alias:server

• Tra cứu người dùng truy vấn thư mục người dùng Matrix trên máy chủ đó.
• Tra cứu phòng chấp nhận ID phòng và bí danh rõ ràng trực tiếp, sau đó quay lại tìm kiếm tên phòng đã tham gia cho tài khoản đó.
• Tra cứu tên phòng đã tham gia là nỗ lực tốt nhất. Nếu một tên phòng không thể được giải quyết thành ID hoặc bí danh, nó sẽ bị bỏ qua bởi quá trình giải quyết danh sách cho phép khi chạy.

​

Tham chiếu cấu hình

• enabled: bật hoặc tắt kênh.
• name: nhãn tùy chọn cho tài khoản.
• defaultAccount: ID tài khoản ưu tiên khi nhiều tài khoản Matrix được cấu hình.
• homeserver: URL máy chủ, ví dụ https://matrix.example.org.
• allowPrivateNetwork: cho phép tài khoản Matrix này kết nối với các máy chủ riêng/nội bộ. Bật điều này khi máy chủ giải quyết đến localhost, một IP LAN/Tailscale, hoặc một máy chủ nội bộ như matrix-synapse.
• userId: ID người dùng Matrix đầy đủ, ví dụ @bot:example.org.
• accessToken: access token cho xác thực dựa trên token.
• password: mật khẩu cho đăng nhập dựa trên mật khẩu.
• deviceId: ID thiết bị Matrix rõ ràng.
• deviceName: tên hiển thị thiết bị cho đăng nhập bằng mật khẩu.
• avatarUrl: URL avatar tự lưu trữ cho đồng bộ hồ sơ và cập nhật set-profile.
• initialSyncLimit: giới hạn sự kiện đồng bộ khởi động.
• encryption: bật E2EE.
• allowlistOnly: buộc hành vi chỉ danh sách cho phép cho DM và phòng.
• groupPolicy: open, allowlist, hoặc disabled.
• groupAllowFrom: danh sách cho phép ID người dùng cho lưu lượng phòng.
• Các mục groupAllowFrom nên là ID người dùng Matrix đầy đủ. Các tên không được giải quyết bị bỏ qua khi chạy.
• replyToMode: off, first, hoặc all.
• threadReplies: off, inbound, hoặc always.
• threadBindings: ghi đè theo kênh cho định tuyến và vòng đời phiên ràng buộc luồng.
• startupVerification: chế độ yêu cầu tự xác minh tự động khi khởi động (if-unverified, off).
• startupVerificationCooldownHours: thời gian chờ trước khi thử lại các yêu cầu xác minh khởi động tự động.
• textChunkLimit: kích thước đoạn tin nhắn gửi ra.
• chunkMode: length hoặc newline.
• responsePrefix: tiền tố tin nhắn tùy chọn cho các trả lời gửi ra.
• ackReaction: ghi đè phản ứng xác nhận tùy chọn cho kênh/tài khoản này.
• ackReactionScope: ghi đè phạm vi phản ứng xác nhận tùy chọn (group-mentions, group-all, direct, all, none, off).
• reactionNotifications: chế độ thông báo phản ứng đến (own, off).
• mediaMaxMb: giới hạn kích thước media gửi ra tính bằng MB.
• autoJoin: chính sách tự động tham gia lời mời (always, allowlist, off). Mặc định: off.
• autoJoinAllowlist: các phòng/bí danh được phép khi autoJoin là allowlist. Các mục bí danh được giải quyết thành ID phòng trong quá trình xử lý lời mời; OpenClaw không tin tưởng trạng thái bí danh được tuyên bố bởi phòng được mời.
• dm: khối chính sách DM (enabled, policy, allowFrom).
• Các mục dm.allowFrom nên là ID người dùng Matrix đầy đủ trừ khi bạn đã giải quyết chúng thông qua tra cứu thư mục trực tiếp.
• accounts: ghi đè theo tài khoản có tên. Các giá trị channels.matrix cấp cao nhất hoạt động như mặc định cho các mục này.
• groups: bản đồ chính sách theo phòng. Ưu tiên ID phòng hoặc bí danh; các tên phòng không được giải quyết bị bỏ qua khi chạy. Danh tính phiên/nhóm sử dụng ID phòng ổn định sau khi giải quyết, trong khi các nhãn có thể đọc được vẫn đến từ tên phòng.
• rooms: bí danh cũ cho groups.
• actions: kiểm soát công cụ theo hành động (messages, reactions, pins, profile, memberInfo, channelInfo, verification).