Meet NanoCo, maintainers of NanoClaw: we raised $12M to give every member of your team a professional assistant →
Skills
Messaging Official

Matrix

Add Matrix as a messaging channel. Works with any Matrix homeserver, including matrix.org and self-hosted Synapse.

What it does

  • Works with any Matrix homeserver (matrix.org, Synapse, Dendrite)
  • Username/password or access token authentication
  • Auto-accept room invites with optional allowlist
  • Optional E2EE cross-signing via recovery key
  • Stable device ID across restarts

What you'll need

  • NanoClaw installed and running
  • A dedicated Matrix account for the bot (separate from your own)
  • Node.js 22+ with strict ESM resolution

Install

/add-matrix

How it works

The /add-matrix skill connects NanoClaw to Matrix via the Beeper Chat SDK adapter. The adapter speaks the Client-Server API to your homeserver and bridges it into NanoClaw’s channel model.

Matrix can’t DM yourself, so the bot needs its own account — typically a fresh registration on matrix.org or your own homeserver.

Setup

Open Element in a private window, register a new account for the bot (e.g. andybot), and grab the user ID (@andybot:matrix.org).

You then choose between two auth methods:

  • Username + password — simplest. The adapter logs in automatically on each startup.
  • Access token — recommended for production. Get one from Element’s Settings → Help & About → Access Token, or via the _matrix/client/r0/login API.

The skill copies the adapter from the channels branch, installs @beeper/chat-adapter-matrix, and runs a small node script to patch ESM extensions in the package’s published dist (Node 22 strict resolution rejects extensionless imports).

What you get

  • Rooms and DMs — group chats, 1:1 conversations, and direct messages all route through the same adapter.
  • Auto-join invites with an optional allowlist (MATRIX_INVITE_AUTOJOIN_ALLOWLIST) restricting which users can pull the bot into rooms.
  • Cross-signing support via MATRIX_RECOVERY_KEY for end-to-end encrypted rooms.
  • Stable device ID via MATRIX_DEVICE_ID so the bot looks like the same client to other users across restarts.

Tips

  • The matrix-js-sdk dist patch in step 5 is idempotent but needs re-running after any pnpm install that touches the adapter. The skill prints the command for that.
  • Matrix’s “Internal room ID” (starts with !) is what NanoClaw uses as the platform ID. Aliases like #general:matrix.org work too.
  • Threads have spotty client support — treat Matrix as flat-message for reliability.
  • Same agent group is fine for rooms where you’re the primary user. Use a separate agent group for community rooms or sensitive contexts.
  • Don’t reuse your personal account — Matrix sees a single account from one device, so any bot work would clobber your personal session.