DEV Community

Hex
Hex

Posted on • Originally published at openclawplaybook.ai

OpenClaw Matrix Integration: Decentralized AI Agent Messaging

#ai #agents #matrix #automation

If you've been running your AI agent on Slack or Discord, you've been renting. Matrix gives you ownership. Your homeserver, your data, your federation rules — and now your AI agent lives there too.

OpenClaw's Matrix plugin supports DMs, rooms, threads, reactions, polls, media, and full end-to-end encryption. This guide walks through everything: from initial setup to production-hardened configs with E2EE, multi-account routing, and inter-agent communication.

Why Matrix for AI Agents?

Matrix is the only major messaging protocol that's federated, open-source, and end-to-end encrypted by default. For AI agent operators, that matters for three reasons:

  • Data sovereignty. Your agent conversations stay on your homeserver. No third-party platform scanning your prompts or responses.
  • Federation. Your agent can interact with users across different Matrix homeservers — no single point of control.
  • Self-hosted infrastructure. Run Synapse or Conduit on your own hardware. Pair it with OpenClaw on the same box or network. Zero external dependencies.

If you're already running a self-hosted OpenClaw on a VPS, adding Matrix keeps your entire AI stack under your control.

Prerequisites

Before you start:

  • OpenClaw installed and running
  • A Matrix account on any homeserver (matrix.org, your own Synapse, Element, etc.)
  • An access token or password for that account

Matrix is a plugin channel — it's not bundled with core OpenClaw. You'll install it first.

Step 1: Install the Matrix Plugin 

openclaw plugins install @openclaw/matrix
Enter fullscreen mode Exit fullscreen mode

That's it. The plugin hooks into OpenClaw's channel system automatically.

Step 2: Configure Your Matrix Connection

You have two auth options: access token (recommended) or password.

Token-Based Auth (Recommended)

Grab your access token from your Matrix client (Element → Settings → Help & About → Access Token) and configure:

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

Password-Based Auth

If you prefer password login, OpenClaw will authenticate and cache the token automatically:

{
  "channels": {
    "matrix": {
      "enabled": true,
      "homeserver": "https://matrix.example.org",
      "userId": "@bot:example.org",
      "password": "your-password-here",
      "deviceName": "OpenClaw Gateway",
      "dm": { "policy": "pairing" }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Interactive Setup

Don't want to edit JSON manually? Use the interactive wizard:

openclaw channels add
# Follow the interactive wizard — it asks for:
# - Homeserver URL
# - Auth method (access token or password)
# - User ID (if password auth)
# - Device name
# - E2EE toggle
# - Room access config
Enter fullscreen mode Exit fullscreen mode

You can also use environment variables: MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN, MATRIX_USER_ID, and MATRIX_PASSWORD.

Step 3: Set Up Access Control

Access control is critical — you don't want random Matrix users burning your API credits. Here's a production config:

{
  "channels": {
    "matrix": {
      "enabled": true,
      "homeserver": "https://matrix.example.org",
      "accessToken": "syt_xxx",
      "encryption": true,
      "dm": {
        "policy": "allowlist",
        "allowFrom": ["@admin:example.org"]
      },
      "groupPolicy": "allowlist",
      "groupAllowFrom": ["@admin:example.org"],
      "groups": {
        "!roomid:example.org": {
          "requireMention": true
        }
      },
      "autoJoin": "allowlist",
      "autoJoinAllowlist": ["!roomid:example.org"],
      "threadReplies": "inbound"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Key points:

  • dm.policy: "allowlist" — only approved Matrix IDs can DM your agent
  • groupPolicy: "allowlist" — only approved users can trigger the agent in rooms
  • requireMention: true — in rooms, the agent only responds when explicitly mentioned
  • autoJoin: "allowlist" — the agent auto-joins only pre-approved rooms
  • threadReplies: "inbound" — replies inside threads when the message came from a thread

For a simpler start, use pairing mode for DMs — users request access, you approve:

# List pending pairing requests
openclaw pairing list matrix

# Approve a specific user
openclaw pairing approve matrix <CODE>
Enter fullscreen mode Exit fullscreen mode

End-to-End Encryption

This is where Matrix shines for AI agent operations. Set encryption: true and your agent's conversations are encrypted end-to-end — even the homeserver admin can't read them.

OpenClaw uses the official matrix-js-sdk Rust crypto path. After enabling encryption, bootstrap cross-signing and verify the device:

# Check verification status
openclaw matrix verify status

# Bootstrap cross-signing
openclaw matrix verify bootstrap

# Verify with recovery key
openclaw matrix verify device "<your-recovery-key>"

# Check room-key backup health
openclaw matrix verify backup status
Enter fullscreen mode Exit fullscreen mode

Tip: Run openclaw matrix verify status --verbose to see full diagnostics including local trust, cross-signing verification, and owner signing status.

Multi-Account Setup

Need separate personas? An assistant account for user interactions and an alerts account for ops notifications?

{
  "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"]
          }
        }
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Top-level values act as defaults — named accounts override what they need to. This is powerful for multi-agent team setups — each agent gets its own Matrix identity while sharing one gateway.

Bot-to-Bot Communication

By default, OpenClaw ignores messages from other configured Matrix accounts to prevent loops. For inter-agent communication, enable it deliberately:

{
  "channels": {
    "matrix": {
      "allowBots": "mentions",
      "groups": {
        "!teamroom:example.org": {
          "requireMention": true
        }
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

The "mentions" mode is the safe choice — agents only process messages from other agents when explicitly mentioned.

Threads and Session Binding

Matrix threads work natively with OpenClaw's session routing. Three thread modes:

  • threadReplies: "off" — all replies go top-level
  • threadReplies: "inbound" — replies stay in-thread when the message was threaded (recommended)
  • threadReplies: "always" — always replies in a thread rooted at the triggering message

Thread bindings work for Matrix too — /focus, /unfocus, /agents, and thread-bound /acp spawn all function in Matrix rooms and DMs.

Private/LAN Homeservers

Running Synapse on your local network or Tailscale? OpenClaw blocks private homeservers by default (SSRF protection), but you can opt in:

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

Perfect for air-gapped or fully self-hosted setups.

Device and DM Hygiene

Over time, old OpenClaw-managed Matrix devices accumulate and complicate E2EE trust. Keep things clean:

# List old devices
openclaw matrix devices list

# Clean up stale ones
openclaw matrix devices prune-stale
Enter fullscreen mode Exit fullscreen mode

If DM routing gets out of sync, repair it:

# Inspect DM mapping for a user
openclaw matrix direct inspect --user-id @alice:example.org

# Repair broken DM routing
openclaw matrix direct repair --user-id @alice:example.org
Enter fullscreen mode Exit fullscreen mode

Reactions and Acknowledgments

Matrix supports full reaction workflows. Your agent can react to messages, list reactions, and remove its own reactions. Inbound reaction notifications are supported too — by default, OpenClaw forwards reactions on bot-authored messages.

Verify Everything Works

After configuration, restart and verify:

# Restart gateway to pick up changes
openclaw gateway restart

# Verify channel is connected
openclaw channels status --probe

# Check Matrix-specific status
openclaw matrix verify status
Enter fullscreen mode Exit fullscreen mode

Then open your Matrix client, start a DM with your agent, and send a message.

Troubleshooting

Common issues and fixes:

  • Agent not responding in rooms: Check requireMention — if true, you need to @-mention the agent. Also verify groupPolicy and groupAllowFrom include your user ID.
  • E2EE messages not decrypting: Run openclaw matrix verify bootstrap --verbose to repair cross-signing state.
  • DM going to wrong room: Use openclaw matrix direct repair --user-id @user:server to fix stale DM mappings.
  • Private homeserver blocked: Add allowPrivateNetwork: true to the account config.
  • Multiple accounts conflicting: Set defaultAccount and use --account <id> for CLI commands.

What Makes This Different

Most AI agent platforms lock you into their messaging layer. OpenClaw on Matrix gives you:

  • Full data ownership — conversations never leave your infrastructure
  • Real E2EE — not just TLS in transit, but actual end-to-end encryption with cross-signing verification
  • Federation — your agent can interact across homeservers without centralized control
  • Multi-account flexibility — different personas, different access policies, one gateway
  • Inter-agent coordination — bot-to-bot communication with proper mention gating

If privacy and infrastructure ownership matter to you, Matrix is the channel to run.

Originally published at openclawplaybook.ai. Get The OpenClaw Playbook — $9.99.

Top comments (0)