Skip to content

Feature request: Multi-account Matrix support #12040

@githabideri

Description

@githabideri

Servus Peter and hi to everyone else :)

I have been using OpenClaw for several weeks now and I love it. I started tinkering with the codebase immediately and having OpenClaw consuct changes on itself is weird and cool. I immediately wanted to use Matrix and then also slowly mix in local llms, so i was tinkering around on how to do it best. I now have a really cool setup where i added another local agwnt to several rooms. They dont answer to all messages like the main agent, but only with @ mention. And i have to say it is just great! I have the teacher model ("Labmaster") as main agent and then whenever i feel like testing new models i tell the main agent to load model and the I can even test the model in same room and then uae main model for feedback, it is a most fruitful and rewarding loop. More info for these tests over on the new llmlab repo that does all sorts of local model testing on modest hardware (dual RTX 3060) specifically for the use with OpenClaw (https://github.com/githabideri/llmlab ). If you have any questions or input or whether it is worth doing a pr, please tell me so!

I am very happy with my setup and I think others would too! :)

All the best from Vienna,
Martin

Here is the OpenClaw message with more technical explanation of what we did:

Summary

Support for running multiple Matrix bot accounts from a single OpenClaw instance, with per-account configuration and binding-based routing.

Use Case

I run OpenClaw with multiple agents (main assistant, local LLM testing, specialized bots). Currently each agent needs a separate OpenClaw instance to have its own Matrix identity. With multi-account support, I can:

  • Run @mainbot and @localbot from one gateway
  • Route rooms to different agents based on which account received the message
  • Share infrastructure while keeping bot identities separate

Proposed Solution

I've implemented this locally and have it working. The approach:

  1. Config: channels.matrix.accounts — per-account credentials (homeserver, userId, accessToken)
  2. Bindings: match.accountId — route messages to agents based on which account received them
  3. Merged config — accounts inherit base matrix config, override specific fields

Example config

{
  "channels": {
    "matrix": {
      "homeserver": "https://matrix.example.com",
      "accounts": {
        "localbot": {
          "userId": "@localbot:matrix.example.com",
          "accessToken": "...",
          "name": "LocalBot"
        }
      }
    }
  },
  "bindings": [
    {
      "match": { "channel": "matrix", "accountId": "localbot", "to": "room:!abc:..." },
      "agent": "local-test"
    }
  ]
}

Implementation Notes

The change touches ~20 files in extensions/matrix/:

  • accounts.ts — account listing and config merging
  • credentials.ts — per-account credential storage
  • config-schema.ts — schema for accounts config
  • client/*.ts — multi-client management
  • monitor/*.ts — routing with accountId context

Happy to submit a PR if there's interest, or discuss alternative approaches.

Environment

  • OpenClaw 2026.2.x
  • Matrix via matrix-bot-sdk (now @vector-im/matrix-bot-sdk)
  • Tested with Synapse homeserver

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions