How to Connect OpenClaw to Matrix

Prerequisites

• ✓An existing Matrix homeserver such as https://matrix.example.org that you can log into.
• ✓A Matrix account for your bot on that homeserver (for example @bot:example.org).
• ✓An OpenClaw gateway installation with access to its config (Matrix is a bundled channel plugin in current OpenClaw releases).
• ✓Either a Matrix access token (for example syt_xxx) or the bot account password so OpenClaw can authenticate.

Steps

1. 1

   Ensure the Matrix plugin is installed

   Matrix ships as a bundled plugin in current OpenClaw releases, so you usually don’t need to install anything. If you’re on an older or custom build that excluded Matrix, install the plugin so the gateway can speak Matrix.

   bashCopy

   openclaw plugins install @openclaw/matrix

2. 2

   Optionally install Matrix from a local checkout

   If you’re developing or vendoring the Matrix plugin locally, install it from your checkout instead of npm. This keeps your gateway using the exact plugin code in your repo.

   bashCopy

   openclaw plugins install ./path/to/local/matrix-plugin

3. 3

   Run the interactive Matrix channel setup

   Use the OpenClaw channel wizard to add Matrix and capture the homeserver, auth method, and DM/room policies. The wizard also offers to keep auth in environment variables when it detects the relevant MATRIX_* vars, which is useful for production deployments.

   bashCopy

   openclaw channels add
   openclaw configure --section channels

4. 4

   Configure Matrix with a minimal token-based setup

   If you already have a Matrix access token, wire it directly into your OpenClaw config. This minimal config enables the Matrix channel, points at your homeserver, and uses DM pairing so new users must be approved before full access.

   jsonCopy

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

5. 5

   Configure Matrix with password-based login instead of a token

   If you prefer to log in with a Matrix user ID and password, use the password-based setup. OpenClaw caches the access token after login so it doesn’t need to re-authenticate on every start.

   jsonCopy

   {
     channels: {
       matrix: {
         enabled: true,
         homeserver: "https://matrix.example.org",
         userId: "@bot:example.org",
         password: "replace-me", // pragma: allowlist secret
         deviceName: "OpenClaw Gateway",
       },
     },
   }
   

6. 6

   Set Matrix auth via environment variables when needed

   For production or containerized deployments, keep credentials out of the main config and use MATRIX_* environment variables instead. OpenClaw reads these when the corresponding config keys are unset, and the wizard can detect them and offer an env-based shortcut.

   textCopy

   MATRIX_HOMESERVER
   MATRIX_ACCESS_TOKEN
   MATRIX_USER_ID
   MATRIX_PASSWORD
   MATRIX_DEVICE_ID
   MATRIX_DEVICE_NAME

7. 7

   Enable auto-join behavior for Matrix invites

   By default the bot ignores new invites, which makes it look broken when you invite it to a room or DM. Decide whether you want it to join all invites or only specific rooms using an allowlist.

   jsonCopy

   {
     channels: {
       matrix: {
         autoJoin: "allowlist",
         autoJoinAllowlist: ["!ops:example.org", "#support:example.org"],
         groups: {
           "!ops:example.org": {
             requireMention: true,
           },
         },
       },
     },
   }
   

8. 8

   Join every Matrix invite when appropriate

   If you’re running in a controlled environment and want the bot to accept all invites, switch autoJoin to always. This is convenient for testing but less safe on public homeservers.

   jsonCopy

   {
     channels: {
       matrix: {
         autoJoin: "always",
       },
     },
   }
   

9. 9

   Enable E2EE for Matrix rooms and DMs

   Turn on encryption when you want OpenClaw to participate in end-to-end encrypted rooms. The Matrix plugin automatically detects E2EE state and handles encrypted thumbnails and attachments.

   jsonCopy

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

10. 10

    Use a practical baseline Matrix configuration

    Once basic connectivity works, tighten DM and room policies and enable streaming previews. This baseline config pairs DMs, restricts groups via allowlists, and turns on partial streaming so users see live drafts.

    jsonCopy

    {
      channels: {
        matrix: {
          enabled: true,
          homeserver: "https://matrix.example.org",
          accessToken: "syt_xxx",
          encryption: true,
    
          dm: {
            policy: "pairing",
            sessionScope: "per-room",
            threadReplies: "off",
          },
    
          groupPolicy: "allowlist",
          groupAllowFrom: ["@admin:example.org"],
          groups: {
            "!roomid:example.org": {
              requireMention: true,
            },
          },
    
          autoJoin: "allowlist",
          autoJoinAllowlist: ["!roomid:example.org"],
          threadReplies: "inbound",
          replyToMode: "off",
          streaming: "partial",
        },
      },
    }
    

11. 11

    Enable streaming previews for Matrix replies

    If you want users to see the assistant typing, enable streaming previews. Partial streaming edits a single preview message in place while the model generates text, which matches how many Matrix clients surface notifications.

    jsonCopy

    {
      channels: {
        matrix: {
          streaming: "partial",
        },
      },
    }
    

12. 12

    Configure quiet streaming with self-hosted push rules (optional)

    On self-hosted homeservers you can use quiet previews that only notify when the reply is finalized. This requires both `streaming: "quiet"` in OpenClaw and a per-user push rule that matches finalized preview edits from your bot.

    jsonCopy

    {
      channels: {
        matrix: {
          streaming: "quiet",
        },
      },
    }
    

13. 13

    Create a Matrix push rule for finalized preview notifications

    Use the Matrix Client-Server API with the recipient’s access token to create an override push rule that fires when OpenClaw finalizes a preview. This makes quiet previews behave like normal notifications only when the reply is done.

    bashCopy

    curl -sS -X PUT \
      "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname" \
      -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      --data '{
        "conditions": [
          { "kind": "event_match", "key": "type", "pattern": "m.room.message" },
          {
            "kind": "event_property_is",
            "key": "content.m\\.relates_to.rel_type",
            "value": "m.replace"
          },
          {
            "kind": "event_property_is",
            "key": "content.com\\.openclaw\\.finalized_preview",
            "value": true
          },
          { "kind": "event_match", "key": "sender", "pattern": "@bot:example.org" }
        ],
        "actions": [
          "notify",
          { "set_tweak": "sound", "value": "default" },
          { "set_tweak": "highlight", "value": false }
        ]
      }'
    

14. 14

    Restart the OpenClaw gateway and invite the bot

    After updating your config, restart the gateway so the Matrix plugin reconnects with the new settings. Then start a DM with the bot or invite it to a room that matches your autoJoin policy so you can verify end-to-end behavior.

Configuration

Troubleshooting

{
  channels: {
    matrix: {
      autoJoin: "always",
    },
  },
}

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

openclaw matrix verify status
openclaw matrix verify bootstrap
openclaw matrix verify backup status

curl -sS -X PUT \
  "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
    "conditions": [
      { "kind": "event_match", "key": "type", "pattern": "m.room.message" },
      {
        "kind": "event_property_is",
        "key": "content.m\\.relates_to.rel_type",
        "value": "m.replace"
      },
      {
        "kind": "event_property_is",
        "key": "content.com\\.openclaw\\.finalized_preview",
        "value": true
      },
      { "kind": "event_match", "key": "sender", "pattern": "@bot:example.org" }
    ],
    "actions": [
      "notify",
      { "set_tweak": "sound", "value": "default" },
      { "set_tweak": "highlight", "value": false }
    ]
  }'

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

Frequently asked questions