OpenClaw Matrix Integration

OpenClaw Matrix Integration

Research notes on integrating OpenClaw with Matrix, focusing on E2E encryption, threading, and group chats.

Overview

OpenClaw connects to Matrix as a regular user on any homeserver via the @openclaw/matrix plugin. The integration uses the @vector-im/matrix-bot-sdk with optional Rust crypto SDK for E2EE.

Installation:

openclaw plugins install @openclaw/matrix

E2E Encryption (E2EE)

How It Works

• Uses the Rust crypto SDK (@matrix-org/matrix-sdk-crypto-nodejs)
• Encryption enabled via channels.matrix.encryption: true
• Crypto state stored in SQLite at ~/.openclaw/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/crypto/

Setup Requirements

1. Enable encryption in config:

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

2. Device verification: On first connection, OpenClaw requests verification from your other sessions. Open Element (or another client) and approve the verification request to establish trust.

3. Crypto module: If you see missing crypto module errors, run:

pnpm rebuild @matrix-org/matrix-sdk-crypto-nodejs
# or
node node_modules/@matrix-org/matrix-sdk-crypto-nodejs/download-lib.js

Key Points

Limitations

• If crypto module cannot load, E2EE is disabled (logged warning)
• Encrypted rooms will not decrypt without proper setup
• Device must be verified for key sharing to work

Threading

Protocol Support

Matrix threads are stable since spec v1.4 (MSC3440). The m.thread relation provides:

• Thread root event ID on every threaded event
• Stable/unique identifier per thread
• Full Element/modern client support

OpenClaw Thread Handling

Current behavior: Threads are treated as reply formatting only, NOT session isolation. All messages in a room (threaded or not) share the same session key:

agent:<agentId>:matrix:room:<roomId>

Configuration options:

{
  channels: {
    matrix: {
      threadReplies: "inbound",  // off | inbound (default) | always
      replyToMode: "off",        // off (default) | first | all
    },
  },
}

Thread Session Isolation (Feature Request)

There’s an open feature request (#29729) for per-thread session isolation:

Proposed session key format:

# Room-level (current)
agent:main:matrix:room:!abc123:example.org

# Thread-level (proposed)
agent:main:matrix:room:!abc123:example.org:thread:$rootEventId

Proposed config:

{
  channels: {
    matrix: {
      thread: {
        historyScope: "thread",    // "thread" | "room" (current behavior)
        inheritParent: false,       // copy parent room transcript
        initialHistoryLimit: 20,    // fetch N existing thread messages
      },
    },
  },
}

Status: Not yet implemented. Currently, Slack and Telegram have thread/topic session isolation, but Matrix does not.

Current Workarounds

1. Use separate rooms instead of threads (heavy, clutters room list)
2. Use /new command to reset session when switching topics
3. Prompt-prefix approach (unreliable, wastes tokens)

Group Chats (Rooms)

Access Control

Default policy: groupPolicy: "allowlist" (mention-gated)

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

Room Configuration Options

Per-Room User Restrictions

{
  groups: {
    "!roomId:example.org": {
      allow: true,
      users: ["@allowed:example.org"],  // restrict to specific users
    },
  },
}

Routing Model

• DMs: Share the agent’s main session
• Rooms: Each room gets its own group session
• Threads: Share parent room session (no isolation currently)

Multi-Account Support

Run multiple Matrix accounts with different configs:

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

• Each account inherits top-level settings (can override)
• Account startup is serialized (avoids race conditions)
• Crypto state is per account + access token
• Use bindings[].match.accountId to route accounts to different agents

Capabilities Summary

Troubleshooting

# Diagnostic ladder
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe
openclaw pairing list matrix

Common issues:

References

• OpenClaw Matrix Docs
• Matrix Spec v1.4 (Threading)
• MSC3440: Threading via m.thread
• OpenClaw Thread Isolation Feature Request
• Matrix Homeserver Hosting Options