mirror of
https://github.com/openclaw/openclaw.git
synced 2026-05-25 08:13:32 +00:00
289 lines
13 KiB
Markdown
289 lines
13 KiB
Markdown
---
|
|
summary: "Matrix support status, capabilities, and configuration"
|
|
read_when:
|
|
- Working on Matrix channel features
|
|
title: "Matrix"
|
|
---
|
|
|
|
# Matrix (plugin)
|
|
|
|
Matrix is an open, decentralized messaging protocol. OpenClaw connects as a Matrix **user**
|
|
on any homeserver, so you need a Matrix account for the bot. Once it is logged in, you can DM
|
|
the bot directly or invite it to rooms (Matrix "groups"). Beeper is a valid client option too,
|
|
but it requires E2EE to be enabled.
|
|
|
|
Status: supported via plugin (`matrix-js-sdk`). Direct messages, rooms, threads, media, reactions,
|
|
polls (send + poll-start as text), location, and E2EE (with crypto support).
|
|
|
|
## Plugin required
|
|
|
|
Matrix ships as a plugin and is not bundled with the core install.
|
|
|
|
Install via CLI (npm registry):
|
|
|
|
```bash
|
|
openclaw plugins install @openclaw/matrix
|
|
```
|
|
|
|
Local checkout (when running from a git repo):
|
|
|
|
```bash
|
|
openclaw plugins install ./extensions/matrix
|
|
```
|
|
|
|
If you choose Matrix during configure/onboarding and a git checkout is detected,
|
|
OpenClaw will offer the local install path automatically.
|
|
|
|
Details: [Plugins](/tools/plugin)
|
|
|
|
## Setup
|
|
|
|
1. Install the Matrix plugin:
|
|
- From npm: `openclaw plugins install @openclaw/matrix`
|
|
- From a local checkout: `openclaw plugins install ./extensions/matrix`
|
|
2. Create a Matrix account on a homeserver:
|
|
- Browse hosting options at [https://matrix.org/ecosystem/hosting/](https://matrix.org/ecosystem/hosting/)
|
|
- Or host it yourself.
|
|
3. Get an access token for the bot account:
|
|
- Use the Matrix login API with `curl` at your home server:
|
|
|
|
```bash
|
|
curl --request POST \
|
|
--url https://matrix.example.org/_matrix/client/v3/login \
|
|
--header 'Content-Type: application/json' \
|
|
--data '{
|
|
"type": "m.login.password",
|
|
"identifier": {
|
|
"type": "m.id.user",
|
|
"user": "your-user-name"
|
|
},
|
|
"password": "your-password"
|
|
}'
|
|
```
|
|
|
|
- Replace `matrix.example.org` with your homeserver URL.
|
|
- Or set `channels.matrix.userId` + `channels.matrix.password`: OpenClaw calls the same
|
|
login endpoint, stores the access token in `~/.openclaw/credentials/matrix/credentials.json`,
|
|
and reuses it on next start.
|
|
- Optional registration mode: set `channels.matrix.register: true` to attempt account creation
|
|
when password login fails (for homeservers that allow open registration).
|
|
|
|
4. Configure credentials:
|
|
- Env: `MATRIX_HOMESERVER`, `MATRIX_ACCESS_TOKEN` (or `MATRIX_USER_ID` + `MATRIX_PASSWORD`)
|
|
- Or config: `channels.matrix.*`
|
|
- If both are set, config takes precedence.
|
|
- With access token: user ID and device ID are fetched automatically via `/whoami` if missing.
|
|
- When set, `channels.matrix.userId` should be the full Matrix ID (example: `@bot:example.org`).
|
|
- Optional: set `channels.matrix.deviceId` (or `MATRIX_DEVICE_ID`) to pin to a known device ID.
|
|
5. Restart the gateway (or finish onboarding).
|
|
6. Start a DM with the bot or invite it to a room from any Matrix client
|
|
(Element, Beeper, etc.; see [https://matrix.org/ecosystem/clients/](https://matrix.org/ecosystem/clients/)). Beeper requires E2EE,
|
|
so set `channels.matrix.encryption: true` and verify the device.
|
|
|
|
Minimal config (access token, user ID auto-fetched):
|
|
|
|
```json5
|
|
{
|
|
channels: {
|
|
matrix: {
|
|
enabled: true,
|
|
homeserver: "https://matrix.example.org",
|
|
accessToken: "syt_***",
|
|
dm: { policy: "pairing" },
|
|
},
|
|
},
|
|
}
|
|
```
|
|
|
|
E2EE config (end to end encryption enabled):
|
|
|
|
```json5
|
|
{
|
|
channels: {
|
|
matrix: {
|
|
enabled: true,
|
|
homeserver: "https://matrix.example.org",
|
|
accessToken: "syt_***",
|
|
encryption: true,
|
|
dm: { policy: "pairing" },
|
|
},
|
|
},
|
|
}
|
|
```
|
|
|
|
## Encryption (E2EE)
|
|
|
|
End-to-end encryption is **supported** via the Rust crypto SDK.
|
|
|
|
Enable with `channels.matrix.encryption: true`:
|
|
|
|
- If the crypto module loads, encrypted rooms are decrypted automatically.
|
|
- Outbound media is encrypted when sending to encrypted rooms.
|
|
- Cross-signing and secret storage are bootstrapped at startup when possible.
|
|
- OpenClaw creates or reuses a recovery key for secret storage and stores it at:
|
|
`~/.openclaw/credentials/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/recovery-key.json`
|
|
- On startup, OpenClaw requests self-verification and can accept incoming verification requests.
|
|
- Verify in another Matrix client (Element, etc.) to establish trust and improve key sharing.
|
|
- If the crypto module cannot be loaded, E2EE is disabled and encrypted rooms will not decrypt;
|
|
OpenClaw logs a warning.
|
|
- If you see missing crypto module errors (for example, `@matrix-org/matrix-sdk-crypto-nodejs-*`),
|
|
allow build scripts for `@matrix-org/matrix-sdk-crypto-nodejs` and run
|
|
`pnpm rebuild @matrix-org/matrix-sdk-crypto-nodejs` or fetch the binary with
|
|
`node node_modules/@matrix-org/matrix-sdk-crypto-nodejs/download-lib.js`.
|
|
|
|
Crypto state is stored per account + access token in
|
|
`~/.openclaw/credentials/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/`.
|
|
Crypto data lives in IndexedDB plus a persisted snapshot (`crypto-idb-snapshot.json`),
|
|
with sync state in `bot-storage.json`.
|
|
If the access token (device) changes, a new store is created and the bot must be
|
|
re-verified for encrypted rooms.
|
|
|
|
**Device verification:**
|
|
When E2EE is enabled, the bot will request verification from your other sessions on startup.
|
|
Open Element (or another client) and approve the verification request to establish trust.
|
|
Once verified, the bot can decrypt messages in encrypted rooms.
|
|
|
|
## Verification operations
|
|
|
|
When E2EE is enabled and `channels.matrix.actions.verification` is on, the Matrix
|
|
`permissions` action exposes verification operations:
|
|
|
|
- `encryption-status`: report encryption and recovery key status.
|
|
- `verification-list`: list tracked verification requests.
|
|
- `verification-request`: start verification (`ownUser`, `userId+deviceId`, or `userId+roomId`).
|
|
- `verification-accept`, `verification-cancel`: accept or cancel a request.
|
|
- `verification-start`: start SAS verification.
|
|
- `verification-sas`, `verification-confirm`, `verification-mismatch`: read and confirm or reject SAS.
|
|
- `verification-generate-qr`, `verification-scan-qr`, `verification-confirm-qr`: QR-based flows.
|
|
|
|
Use these via the `permissions` action by setting `operation` (or `mode`) to one of:
|
|
`encryption-status`, `verification-list`, `verification-request`, `verification-accept`,
|
|
`verification-cancel`, `verification-start`, `verification-generate-qr`,
|
|
`verification-scan-qr`, `verification-sas`, `verification-confirm`,
|
|
`verification-mismatch`, `verification-confirm-qr`.
|
|
|
|
## Routing model
|
|
|
|
- Replies always go back to Matrix.
|
|
- DMs share the agent's main session; rooms map to group sessions.
|
|
|
|
## Access control (DMs)
|
|
|
|
- Default: `channels.matrix.dm.policy = "pairing"`. Unknown senders get a pairing code.
|
|
- Approve via:
|
|
- `openclaw pairing list matrix`
|
|
- `openclaw pairing approve matrix <CODE>`
|
|
- Public DMs: `channels.matrix.dm.policy="open"` plus `channels.matrix.dm.allowFrom=["*"]`.
|
|
- `channels.matrix.dm.allowFrom` accepts full Matrix user IDs (example: `@user:server`). The wizard resolves display names to user IDs when directory search finds a single exact match.
|
|
|
|
## Rooms (groups)
|
|
|
|
- Default: `channels.matrix.groupPolicy = "allowlist"` (mention-gated). Use `channels.defaults.groupPolicy` to override the default when unset.
|
|
- Allowlist rooms with `channels.matrix.groups` (room IDs or aliases; names are resolved to IDs when directory search finds a single exact match):
|
|
|
|
```json5
|
|
{
|
|
channels: {
|
|
matrix: {
|
|
groupPolicy: "allowlist",
|
|
groups: {
|
|
"!roomId:example.org": { allow: true },
|
|
"#alias:example.org": { allow: true },
|
|
},
|
|
groupAllowFrom: ["@owner:example.org"],
|
|
},
|
|
},
|
|
}
|
|
```
|
|
|
|
- `requireMention: false` enables auto-reply in that room.
|
|
- `groups."*"` can set defaults for mention gating across rooms.
|
|
- `groupAllowFrom` restricts which senders can trigger the bot in rooms (full Matrix user IDs).
|
|
- Per-room `users` allowlists can further restrict senders inside a specific room (use full Matrix user IDs).
|
|
- The configure wizard prompts for room allowlists (room IDs, aliases, or names) and resolves names only on an exact, unique match.
|
|
- On startup, OpenClaw resolves room/user names in allowlists to IDs and logs the mapping; unresolved entries are ignored for allowlist matching.
|
|
- Invites are auto-joined by default; control with `channels.matrix.autoJoin` and `channels.matrix.autoJoinAllowlist`.
|
|
- To allow **no rooms**, set `channels.matrix.groupPolicy: "disabled"` (or keep an empty allowlist).
|
|
- Legacy key: `channels.matrix.rooms` (same shape as `groups`).
|
|
|
|
## Threads
|
|
|
|
- Reply threading is supported.
|
|
- `channels.matrix.threadReplies` controls whether replies stay in threads:
|
|
- `off`, `inbound` (default), `always`
|
|
- `channels.matrix.replyToMode` controls reply-to metadata when not replying in a thread:
|
|
- `off` (default), `first`, `all`
|
|
|
|
## Capabilities
|
|
|
|
| Feature | Status |
|
|
| --------------- | ------------------------------------------------------------------------------------- |
|
|
| Direct messages | ✅ Supported |
|
|
| Rooms | ✅ Supported |
|
|
| Threads | ✅ Supported |
|
|
| Media | ✅ Supported |
|
|
| E2EE | ✅ Supported (crypto module required) |
|
|
| Reactions | ✅ Supported (send/read via tools) |
|
|
| Polls | ✅ Send supported; inbound poll starts are converted to text (responses/ends ignored) |
|
|
| Location | ✅ Supported (geo URI; altitude ignored) |
|
|
| Native commands | ✅ Supported |
|
|
|
|
## Troubleshooting
|
|
|
|
Run this ladder first:
|
|
|
|
```bash
|
|
openclaw status
|
|
openclaw gateway status
|
|
openclaw logs --follow
|
|
openclaw doctor
|
|
openclaw channels status --probe
|
|
```
|
|
|
|
Then confirm DM pairing state if needed:
|
|
|
|
```bash
|
|
openclaw pairing list matrix
|
|
```
|
|
|
|
Common failures:
|
|
|
|
- Logged in but room messages ignored: room blocked by `groupPolicy` or room allowlist.
|
|
- DMs ignored: sender pending approval when `channels.matrix.dm.policy="pairing"`.
|
|
- Encrypted rooms fail: crypto support or encryption settings mismatch.
|
|
|
|
For triage flow: [/channels/troubleshooting](/channels/troubleshooting).
|
|
|
|
## Configuration reference (Matrix)
|
|
|
|
Full configuration: [Configuration](/gateway/configuration)
|
|
|
|
Provider options:
|
|
|
|
- `channels.matrix.enabled`: enable/disable channel startup.
|
|
- `channels.matrix.homeserver`: homeserver URL.
|
|
- `channels.matrix.userId`: Matrix user ID (optional with access token).
|
|
- `channels.matrix.accessToken`: access token.
|
|
- `channels.matrix.password`: password for login (token stored).
|
|
- `channels.matrix.register`: try account registration if password login fails.
|
|
- `channels.matrix.deviceId`: preferred device ID (used for E2EE initialization).
|
|
- `channels.matrix.deviceName`: device display name.
|
|
- `channels.matrix.encryption`: enable E2EE (default: false).
|
|
- `channels.matrix.initialSyncLimit`: initial sync limit.
|
|
- `channels.matrix.threadReplies`: `off | inbound | always` (default: inbound).
|
|
- `channels.matrix.textChunkLimit`: outbound text chunk size (chars).
|
|
- `channels.matrix.chunkMode`: `length` (default) or `newline` to split on blank lines (paragraph boundaries) before length chunking.
|
|
- `channels.matrix.dm.policy`: `pairing | allowlist | open | disabled` (default: pairing).
|
|
- `channels.matrix.dm.allowFrom`: DM allowlist (full Matrix user IDs). `open` requires `"*"`. The wizard resolves names to IDs when possible.
|
|
- `channels.matrix.groupPolicy`: `allowlist | open | disabled` (default: allowlist).
|
|
- `channels.matrix.groupAllowFrom`: allowlisted senders for group messages (full Matrix user IDs).
|
|
- `channels.matrix.allowlistOnly`: force allowlist rules for DMs + rooms.
|
|
- `channels.matrix.groups`: group allowlist + per-room settings map.
|
|
- `channels.matrix.rooms`: legacy group allowlist/config.
|
|
- `channels.matrix.replyToMode`: reply-to mode for threads/tags.
|
|
- `channels.matrix.mediaMaxMb`: inbound/outbound media cap (MB).
|
|
- `channels.matrix.autoJoin`: invite handling (`always | allowlist | off`, default: always).
|
|
- `channels.matrix.autoJoinAllowlist`: allowed room IDs/aliases for auto-join.
|
|
- `channels.matrix.actions`: per-action tool gating (reactions/messages/pins/memberInfo/channelInfo).
|
|
- `channels.matrix.actions.verification`: enable verification action operations.
|