How to Connect OpenClaw to Matrix and Element

Introduction

Matrix is an open, decentralized instant messaging protocol, and Element is its most popular client. By connecting OpenClaw to the Matrix network, you can chat with your AI assistant from any Matrix client while enjoying the privacy protection and decentralization benefits that the Matrix protocol provides.

This tutorial will walk you through the entire process of integrating OpenClaw with Matrix from scratch.

Prerequisites

Before getting started, make sure the following requirements are met:

If you haven't installed OpenClaw yet, run:

npm install -g openclaw@latest
openclaw onboard

Step 1: Create a Matrix Bot Account

You need to create a dedicated Matrix account for OpenClaw. It's recommended to register using the Element client.

Register on matrix.org

1. Visit Element Web and click "Create Account"
2. Select matrix.org as the Homeserver (or use your self-hosted Homeserver address)
3. Choose a username — something like openclaw-bot is recommended
4. Set a strong password and complete the registration

Register on a Self-Hosted Synapse

If you're running your own Synapse server, you can register via the command line:

# Run on the Synapse server
register_new_matrix_user -c /etc/synapse/homeserver.yaml http://localhost:8008
# Follow the prompts to enter a username and password, select no for admin

Step 2: Obtain an Access Token

OpenClaw requires an Access Token to authenticate with the Matrix account. There are two ways to obtain one.

Option 1: Via the Element Client

1. Log in to Element with the bot account
2. Click the avatar in the top-left corner → "All settings"
3. Navigate to the "Help & About" tab
4. Expand the "Advanced" section at the bottom
5. Find the "Access token" field and click to copy

Option 2: Via the API

curl -X POST "https://matrix.org/_matrix/client/v3/login" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "m.login.password",
    "user": "@openclaw-bot:matrix.org",
    "password": "your-password-here"
  }'

The response will contain an access_token field:

{
  "user_id": "@openclaw-bot:matrix.org",
  "access_token": "syt_b3BlbmNsYXctYm90_xxxxxxxxxxxxx_xxxxxx",
  "device_id": "ABCDEFGHIJ"
}

Keep this token safe and do not share it with anyone.

Step 3: Configure OpenClaw

Edit the OpenClaw configuration file at ~/.config/openclaw/openclaw.json5:

{
  // Other settings...
  channels: {
    matrix: {
      enabled: true,
      // Matrix Homeserver URL
      homeserverUrl: "https://matrix.org",
      // Bot's full Matrix ID
      userId: "@openclaw-bot:matrix.org",
      // Access Token obtained in the previous step
      accessToken: "syt_b3BlbmNsYXctYm90_xxxxxxxxxxxxx_xxxxxx",
      // Automatically join rooms when invited
      autoJoin: true,
      // Response mode: all responds to all messages, mention responds only when @mentioned
      responseMode: "mention",
      // Allowed rooms list (empty means all rooms are allowed)
      allowedRooms: [],
      // Display name
      displayName: "OpenClaw AI",
      // Avatar URL (optional)
      avatarUrl: ""
    }
  }
}

Configuration Reference

Step 4: Start and Verify

After saving the configuration, restart OpenClaw:

openclaw restart

Check the logs to confirm the Matrix channel is connected:

openclaw logs

You should see output similar to:

[INFO] Matrix channel initializing...
[INFO] Connected to homeserver: https://matrix.org
[INFO] Logged in as @openclaw-bot:matrix.org
[INFO] Matrix channel ready, listening for messages

Step 5: Create a Room and Invite the Bot

Create a Dedicated Room

1. In Element, click "+" to create a new room
2. Set the room name to something like "AI Assistant"
3. Choose whether to enable encryption based on your needs (see the encryption section below)
4. After creating the room, invite the bot account to join

Invite the Bot

Invite the bot by entering this command in the room:

/invite @openclaw-bot:matrix.org

If you configured autoJoin: true, the bot will automatically accept the invitation and join the room.

Test the Conversation

Send a message in the room to test:

@openclaw-bot Hello, please introduce yourself

If responseMode is set to all, the bot will respond without needing to be @mentioned.

End-to-End Encryption Considerations

Matrix's end-to-end encryption (E2EE) is a powerful privacy feature, but it requires extra attention when integrating with bots.

Current Limitations

OpenClaw's Matrix integration supports E2EE, but keep the following in mind:

1. Device Verification: On first launch, the bot needs to complete device verification. It's recommended to manually verify the bot's device in Element
2. Key Backup: Enabling key backup is recommended; otherwise, OpenClaw may not be able to read older encrypted messages after a restart
3. Performance Overhead: E2EE adds latency to message processing

Enabling Encrypted Room Support

Add E2EE-related settings to your configuration:

{
  channels: {
    matrix: {
      // ...base configuration...
      encryption: {
        enabled: true,
        // Path for storing encryption keys
        storePath: "~/.openclaw/matrix-crypto-store",
        // Whether to automatically verify new devices
        autoVerify: false
      }
    }
  }
}

Verifying the Bot's Device

Complete device verification in Element:

1. Open a direct chat with the bot
2. Click the bot's avatar → "Security"
3. Select "Manually verify by text" or use emoji verification
4. Follow the prompts to complete the verification process

Restricting Room Access

For security purposes, it's recommended to restrict the bot to respond only in specific rooms:

{
  channels: {
    matrix: {
      // Only respond to messages in these rooms
      allowedRooms: [
        "!abcdefg:matrix.org",    // AI Assistant room
        "!hijklmn:matrix.org"     // Team discussion room
      ]
    }
  }
}

To find a room ID: go to room settings in Element → "Advanced" → copy the "Internal room ID".

Using Bridges to Connect Other Platforms

One of Matrix's most powerful features is the ability to connect to other platforms via bridges. When used with OpenClaw, a single bot account can serve multiple platforms simultaneously.

Common bridges include:

Through bridges, messages are automatically synced between Matrix and the target platform, so OpenClaw only needs to connect to Matrix.

Troubleshooting

Bot Cannot Connect to the Homeserver

# Check if the Homeserver is reachable
curl -s https://matrix.org/_matrix/client/versions

# Verify the Access Token is valid
curl -s -H "Authorization: Bearer YOUR_TOKEN" \
  "https://matrix.org/_matrix/client/v3/account/whoami"

Bot Doesn't Respond to Messages

1. Confirm that responseMode is set correctly
2. Check that allowedRooms includes the current room
3. Look for error messages in the OpenClaw logs: openclaw logs

Cannot Decrypt Messages in Encrypted Rooms

1. Confirm that encryption.enabled is set to true
2. Check that the crypto-store path is correct and has write permissions
3. Redo the device verification process

Summary

Through this tutorial, you've successfully connected OpenClaw to the Matrix network. Matrix's decentralized architecture and end-to-end encryption capabilities make it an ideal choice for privacy-conscious users. Combined with OpenClaw's AI capabilities, you can enjoy intelligent assistant services in Element or any Matrix-compatible client.

Next steps:

• Refer to the "Connecting OpenClaw to Multiple Chat Channels" tutorial to set up multi-platform access
• Explore the ClawHub skill marketplace to add more capabilities to your bot