133 lines
5.0 KiB
Markdown
133 lines
5.0 KiB
Markdown
---
|
||
summary: "Matrix support status, capabilities, and configuration"
|
||
read_when:
|
||
- Working on Matrix channel features
|
||
---
|
||
# Matrix (plugin)
|
||
|
||
Status: supported via plugin (matrix-js-sdk). Direct messages, rooms, threads, media, reactions, and polls.
|
||
|
||
## Plugin required
|
||
Matrix ships as a plugin and is not bundled with the core install.
|
||
|
||
Install via CLI (npm registry):
|
||
```bash
|
||
clawdbot plugins install @clawdbot/matrix
|
||
```
|
||
|
||
Local checkout (when running from a git repo):
|
||
```bash
|
||
clawdbot plugins install ./extensions/matrix
|
||
```
|
||
|
||
If you choose Matrix during configure/onboarding and a git checkout is detected,
|
||
Clawdbot will offer the local install path automatically.
|
||
|
||
Details: [Plugins](/plugin)
|
||
|
||
## Quick setup (beginner)
|
||
1) Install the Matrix plugin:
|
||
- From npm: `clawdbot plugins install @clawdbot/matrix`
|
||
- From a local checkout: `clawdbot plugins install ./extensions/matrix`
|
||
2) Configure credentials:
|
||
- Env: `MATRIX_HOMESERVER`, `MATRIX_USER_ID`, `MATRIX_ACCESS_TOKEN` (or `MATRIX_PASSWORD`)
|
||
- Or config: `channels.matrix.*`
|
||
- If both are set, config takes precedence.
|
||
3) Restart the gateway (or finish onboarding).
|
||
4) DM access defaults to pairing; approve the pairing code on first contact.
|
||
|
||
Runtime note: Matrix requires Node.js (Bun is not supported).
|
||
|
||
Minimal config:
|
||
```json5
|
||
{
|
||
channels: {
|
||
matrix: {
|
||
enabled: true,
|
||
homeserver: "https://matrix.example.org",
|
||
userId: "@clawdbot:example.org",
|
||
accessToken: "syt_***",
|
||
dm: { policy: "pairing" }
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## Encryption (E2EE)
|
||
End-to-end encrypted rooms are **not** supported.
|
||
- Use unencrypted rooms or disable encryption when creating the room.
|
||
- If a room is E2EE, the bot will receive encrypted events and won’t reply.
|
||
|
||
## What it is
|
||
Matrix is an open messaging protocol. Clawdbot connects as a Matrix user and listens to DMs and rooms.
|
||
- A Matrix user account owned by the Gateway.
|
||
- Deterministic routing: replies 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:
|
||
- `clawdbot pairing list matrix`
|
||
- `clawdbot pairing approve matrix <CODE>`
|
||
- Public DMs: `channels.matrix.dm.policy="open"` plus `channels.matrix.dm.allowFrom=["*"]`.
|
||
- `channels.matrix.dm.allowFrom` accepts user IDs or display names. The wizard resolves display names to user IDs when directory search is available.
|
||
|
||
## Rooms (groups)
|
||
- Default: `channels.matrix.groupPolicy = "allowlist"` (mention-gated). Use `channels.defaults.groupPolicy` to override the default when unset.
|
||
- Allowlist rooms with `channels.matrix.rooms`:
|
||
```json5
|
||
{
|
||
channels: {
|
||
matrix: {
|
||
rooms: {
|
||
"!roomId:example.org": { requireMention: true }
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
- `requireMention: false` enables auto-reply in that room.
|
||
- The configure wizard prompts for room allowlists (room IDs, aliases, or names) and resolves names when possible.
|
||
- On startup, Clawdbot resolves room/user names in allowlists to IDs and logs the mapping; unresolved entries are kept as typed.
|
||
- To allow **no rooms**, set `channels.matrix.groupPolicy: "disabled"` (or keep an empty allowlist).
|
||
|
||
## Threads
|
||
- Reply threading is supported.
|
||
- `channels.matrix.replyToMode` controls replies when tagged:
|
||
- `off` (default), `first`, `all`
|
||
|
||
## Capabilities
|
||
| Feature | Status |
|
||
|---------|--------|
|
||
| Direct messages | ✅ Supported |
|
||
| Rooms | ✅ Supported |
|
||
| Threads | ✅ Supported |
|
||
| Media | ✅ Supported |
|
||
| Reactions | ✅ Supported |
|
||
| Polls | ✅ Supported |
|
||
| Native commands | ✅ Supported |
|
||
|
||
## 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.
|
||
- `channels.matrix.accessToken`: access token.
|
||
- `channels.matrix.password`: password for login (token stored).
|
||
- `channels.matrix.deviceName`: device display name.
|
||
- `channels.matrix.initialSyncLimit`: initial sync limit.
|
||
- `channels.matrix.threadReplies`: `off | inbound | always` (default: inbound).
|
||
- `channels.matrix.textChunkLimit`: outbound text chunk size (chars).
|
||
- `channels.matrix.dm.policy`: `pairing | allowlist | open | disabled` (default: pairing).
|
||
- `channels.matrix.dm.allowFrom`: DM allowlist (user IDs or display names). `open` requires `"*"`. The wizard resolves names to IDs when possible.
|
||
- `channels.matrix.groupPolicy`: `allowlist | open | disabled` (default: allowlist).
|
||
- `channels.matrix.allowlistOnly`: force allowlist rules for DMs + rooms.
|
||
- `channels.matrix.rooms`: per-room settings and allowlist.
|
||
- `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).
|