Selig
4c966a3ad2
6 custom skills (assign-task, dispatch-webhook, daily-briefing, task-capture, qmd-brain, tts-voice) with technical documentation. Compatible with Claude Code, OpenClaw, Codex CLI, and OpenCode.
75 lines
14 KiB
JSON
Executable File
75 lines
14 KiB
JSON
Executable File
{
|
|
"title": "Matrix (plugin)",
|
|
"content": "Matrix is an open, decentralized messaging protocol. OpenClaw connects as a Matrix **user**\non any homeserver, so you need a Matrix account for the bot. Once it is logged in, you can DM\nthe bot directly or invite it to rooms (Matrix \"groups\"). Beeper is a valid client option too,\nbut it requires E2EE to be enabled.\n\nStatus: supported via plugin (@vector-im/matrix-bot-sdk). Direct messages, rooms, threads, media, reactions,\npolls (send + poll-start as text), location, and E2EE (with crypto support).\n\nMatrix ships as a plugin and is not bundled with the core install.\n\nInstall via CLI (npm registry):\n\nLocal checkout (when running from a git repo):\n\nIf you choose Matrix during configure/onboarding and a git checkout is detected,\nOpenClaw will offer the local install path automatically.\n\nDetails: [Plugins](/plugin)\n\n1. Install the Matrix plugin:\n * From npm: `openclaw plugins install @openclaw/matrix`\n * From a local checkout: `openclaw plugins install ./extensions/matrix`\n\n2. Create a Matrix account on a homeserver:\n * Browse hosting options at [https://matrix.org/ecosystem/hosting/](https://matrix.org/ecosystem/hosting/)\n * Or host it yourself.\n\n3. Get an access token for the bot account:\n\n* Use the Matrix login API with `curl` at your home server:\n\n* Replace `matrix.example.org` with your homeserver URL.\n * Or set `channels.matrix.userId` + `channels.matrix.password`: OpenClaw calls the same\n login endpoint, stores the access token in `~/.openclaw/credentials/matrix/credentials.json`,\n and reuses it on next start.\n\n4. Configure credentials:\n * Env: `MATRIX_HOMESERVER`, `MATRIX_ACCESS_TOKEN` (or `MATRIX_USER_ID` + `MATRIX_PASSWORD`)\n * Or config: `channels.matrix.*`\n * If both are set, config takes precedence.\n * With access token: user ID is fetched automatically via `/whoami`.\n * When set, `channels.matrix.userId` should be the full Matrix ID (example: `@bot:example.org`).\n\n5. Restart the gateway (or finish onboarding).\n\n6. Start a DM with the bot or invite it to a room from any Matrix client\n (Element, Beeper, etc.; see [https://matrix.org/ecosystem/clients/](https://matrix.org/ecosystem/clients/)). Beeper requires E2EE,\n so set `channels.matrix.encryption: true` and verify the device.\n\nMinimal config (access token, user ID auto-fetched):\n\nE2EE config (end to end encryption enabled):\n\nEnd-to-end encryption is **supported** via the Rust crypto SDK.\n\nEnable with `channels.matrix.encryption: true`:\n\n* If the crypto module loads, encrypted rooms are decrypted automatically.\n* Outbound media is encrypted when sending to encrypted rooms.\n* On first connection, OpenClaw requests device verification from your other sessions.\n* Verify the device in another Matrix client (Element, etc.) to enable key sharing.\n* If the crypto module cannot be loaded, E2EE is disabled and encrypted rooms will not decrypt;\n OpenClaw logs a warning.\n* If you see missing crypto module errors (for example, `@matrix-org/matrix-sdk-crypto-nodejs-*`),\n allow build scripts for `@matrix-org/matrix-sdk-crypto-nodejs` and run\n `pnpm rebuild @matrix-org/matrix-sdk-crypto-nodejs` or fetch the binary with\n `node node_modules/@matrix-org/matrix-sdk-crypto-nodejs/download-lib.js`.\n\nCrypto state is stored per account + access token in\n`~/.openclaw/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/crypto/`\n(SQLite database). Sync state lives alongside it in `bot-storage.json`.\nIf the access token (device) changes, a new store is created and the bot must be\nre-verified for encrypted rooms.\n\n**Device verification:**\nWhen E2EE is enabled, the bot will request verification from your other sessions on startup.\nOpen Element (or another client) and approve the verification request to establish trust.\nOnce verified, the bot can decrypt messages in encrypted rooms.\n\n* Replies always go back to Matrix.\n* DMs share the agent's main session; rooms map to group sessions.\n\n## Access control (DMs)\n\n* Default: `channels.matrix.dm.policy = \"pairing\"`. Unknown senders get a pairing code.\n* Approve via:\n * `openclaw pairing list matrix`\n * `openclaw pairing approve matrix <CODE>`\n* Public DMs: `channels.matrix.dm.policy=\"open\"` plus `channels.matrix.dm.allowFrom=[\"*\"]`.\n* `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.\n\n* Default: `channels.matrix.groupPolicy = \"allowlist\"` (mention-gated). Use `channels.defaults.groupPolicy` to override the default when unset.\n* Allowlist rooms with `channels.matrix.groups` (room IDs or aliases; names are resolved to IDs when directory search finds a single exact match):\n\n* `requireMention: false` enables auto-reply in that room.\n* `groups.\"*\"` can set defaults for mention gating across rooms.\n* `groupAllowFrom` restricts which senders can trigger the bot in rooms (full Matrix user IDs).\n* Per-room `users` allowlists can further restrict senders inside a specific room (use full Matrix user IDs).\n* The configure wizard prompts for room allowlists (room IDs, aliases, or names) and resolves names only on an exact, unique match.\n* On startup, OpenClaw resolves room/user names in allowlists to IDs and logs the mapping; unresolved entries are ignored for allowlist matching.\n* Invites are auto-joined by default; control with `channels.matrix.autoJoin` and `channels.matrix.autoJoinAllowlist`.\n* To allow **no rooms**, set `channels.matrix.groupPolicy: \"disabled\"` (or keep an empty allowlist).\n* Legacy key: `channels.matrix.rooms` (same shape as `groups`).\n\n* Reply threading is supported.\n* `channels.matrix.threadReplies` controls whether replies stay in threads:\n * `off`, `inbound` (default), `always`\n* `channels.matrix.replyToMode` controls reply-to metadata when not replying in a thread:\n * `off` (default), `first`, `all`\n\n| Feature | Status |\n| --------------- | ------------------------------------------------------------------------------------ |\n| Direct messages | ✅ Supported |\n| Rooms | ✅ Supported |\n| Threads | ✅ Supported |\n| Media | ✅ Supported |\n| E2EE | ✅ Supported (crypto module required) |\n| Reactions | ✅ Supported (send/read via tools) |\n| Polls | ✅ Send supported; inbound poll starts are converted to text (responses/ends ignored) |\n| Location | ✅ Supported (geo URI; altitude ignored) |\n| Native commands | ✅ Supported |\n\n## Configuration reference (Matrix)\n\nFull configuration: [Configuration](/gateway/configuration)\n\n* `channels.matrix.enabled`: enable/disable channel startup.\n* `channels.matrix.homeserver`: homeserver URL.\n* `channels.matrix.userId`: Matrix user ID (optional with access token).\n* `channels.matrix.accessToken`: access token.\n* `channels.matrix.password`: password for login (token stored).\n* `channels.matrix.deviceName`: device display name.\n* `channels.matrix.encryption`: enable E2EE (default: false).\n* `channels.matrix.initialSyncLimit`: initial sync limit.\n* `channels.matrix.threadReplies`: `off | inbound | always` (default: inbound).\n* `channels.matrix.textChunkLimit`: outbound text chunk size (chars).\n* `channels.matrix.chunkMode`: `length` (default) or `newline` to split on blank lines (paragraph boundaries) before length chunking.\n* `channels.matrix.dm.policy`: `pairing | allowlist | open | disabled` (default: pairing).\n* `channels.matrix.dm.allowFrom`: DM allowlist (full Matrix user IDs). `open` requires `\"*\"`. The wizard resolves names to IDs when possible.\n* `channels.matrix.groupPolicy`: `allowlist | open | disabled` (default: allowlist).\n* `channels.matrix.groupAllowFrom`: allowlisted senders for group messages (full Matrix user IDs).\n* `channels.matrix.allowlistOnly`: force allowlist rules for DMs + rooms.\n* `channels.matrix.groups`: group allowlist + per-room settings map.\n* `channels.matrix.rooms`: legacy group allowlist/config.\n* `channels.matrix.replyToMode`: reply-to mode for threads/tags.\n* `channels.matrix.mediaMaxMb`: inbound/outbound media cap (MB).\n* `channels.matrix.autoJoin`: invite handling (`always | allowlist | off`, default: always).\n* `channels.matrix.autoJoinAllowlist`: allowed room IDs/aliases for auto-join.\n* `channels.matrix.actions`: per-action tool gating (reactions/messages/pins/memberInfo/channelInfo).",
|
|
"code_samples": [
|
|
{
|
|
"code": "Local checkout (when running from a git repo):",
|
|
"language": "unknown"
|
|
},
|
|
{
|
|
"code": "If you choose Matrix during configure/onboarding and a git checkout is detected,\nOpenClaw will offer the local install path automatically.\n\nDetails: [Plugins](/plugin)\n\n## Setup\n\n1. Install the Matrix plugin:\n * From npm: `openclaw plugins install @openclaw/matrix`\n * From a local checkout: `openclaw plugins install ./extensions/matrix`\n\n2. Create a Matrix account on a homeserver:\n * Browse hosting options at [https://matrix.org/ecosystem/hosting/](https://matrix.org/ecosystem/hosting/)\n * Or host it yourself.\n\n3. Get an access token for the bot account:\n\n * Use the Matrix login API with `curl` at your home server:",
|
|
"language": "unknown"
|
|
},
|
|
{
|
|
"code": "* Replace `matrix.example.org` with your homeserver URL.\n * Or set `channels.matrix.userId` + `channels.matrix.password`: OpenClaw calls the same\n login endpoint, stores the access token in `~/.openclaw/credentials/matrix/credentials.json`,\n and reuses it on next start.\n\n4. Configure credentials:\n * Env: `MATRIX_HOMESERVER`, `MATRIX_ACCESS_TOKEN` (or `MATRIX_USER_ID` + `MATRIX_PASSWORD`)\n * Or config: `channels.matrix.*`\n * If both are set, config takes precedence.\n * With access token: user ID is fetched automatically via `/whoami`.\n * When set, `channels.matrix.userId` should be the full Matrix ID (example: `@bot:example.org`).\n\n5. Restart the gateway (or finish onboarding).\n\n6. Start a DM with the bot or invite it to a room from any Matrix client\n (Element, Beeper, etc.; see [https://matrix.org/ecosystem/clients/](https://matrix.org/ecosystem/clients/)). Beeper requires E2EE,\n so set `channels.matrix.encryption: true` and verify the device.\n\nMinimal config (access token, user ID auto-fetched):",
|
|
"language": "unknown"
|
|
},
|
|
{
|
|
"code": "E2EE config (end to end encryption enabled):",
|
|
"language": "unknown"
|
|
},
|
|
{
|
|
"code": "## Encryption (E2EE)\n\nEnd-to-end encryption is **supported** via the Rust crypto SDK.\n\nEnable with `channels.matrix.encryption: true`:\n\n* If the crypto module loads, encrypted rooms are decrypted automatically.\n* Outbound media is encrypted when sending to encrypted rooms.\n* On first connection, OpenClaw requests device verification from your other sessions.\n* Verify the device in another Matrix client (Element, etc.) to enable key sharing.\n* If the crypto module cannot be loaded, E2EE is disabled and encrypted rooms will not decrypt;\n OpenClaw logs a warning.\n* If you see missing crypto module errors (for example, `@matrix-org/matrix-sdk-crypto-nodejs-*`),\n allow build scripts for `@matrix-org/matrix-sdk-crypto-nodejs` and run\n `pnpm rebuild @matrix-org/matrix-sdk-crypto-nodejs` or fetch the binary with\n `node node_modules/@matrix-org/matrix-sdk-crypto-nodejs/download-lib.js`.\n\nCrypto state is stored per account + access token in\n`~/.openclaw/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/crypto/`\n(SQLite database). Sync state lives alongside it in `bot-storage.json`.\nIf the access token (device) changes, a new store is created and the bot must be\nre-verified for encrypted rooms.\n\n**Device verification:**\nWhen E2EE is enabled, the bot will request verification from your other sessions on startup.\nOpen Element (or another client) and approve the verification request to establish trust.\nOnce verified, the bot can decrypt messages in encrypted rooms.\n\n## Routing model\n\n* Replies always go back to Matrix.\n* DMs share the agent's main session; rooms map to group sessions.\n\n## Access control (DMs)\n\n* Default: `channels.matrix.dm.policy = \"pairing\"`. Unknown senders get a pairing code.\n* Approve via:\n * `openclaw pairing list matrix`\n * `openclaw pairing approve matrix <CODE>`\n* Public DMs: `channels.matrix.dm.policy=\"open\"` plus `channels.matrix.dm.allowFrom=[\"*\"]`.\n* `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.\n\n## Rooms (groups)\n\n* Default: `channels.matrix.groupPolicy = \"allowlist\"` (mention-gated). Use `channels.defaults.groupPolicy` to override the default when unset.\n* Allowlist rooms with `channels.matrix.groups` (room IDs or aliases; names are resolved to IDs when directory search finds a single exact match):",
|
|
"language": "unknown"
|
|
}
|
|
],
|
|
"headings": [
|
|
{
|
|
"level": "h2",
|
|
"text": "Plugin required",
|
|
"id": "plugin-required"
|
|
},
|
|
{
|
|
"level": "h2",
|
|
"text": "Setup",
|
|
"id": "setup"
|
|
},
|
|
{
|
|
"level": "h2",
|
|
"text": "Encryption (E2EE)",
|
|
"id": "encryption-(e2ee)"
|
|
},
|
|
{
|
|
"level": "h2",
|
|
"text": "Routing model",
|
|
"id": "routing-model"
|
|
},
|
|
{
|
|
"level": "h2",
|
|
"text": "Access control (DMs)",
|
|
"id": "access-control-(dms)"
|
|
},
|
|
{
|
|
"level": "h2",
|
|
"text": "Rooms (groups)",
|
|
"id": "rooms-(groups)"
|
|
},
|
|
{
|
|
"level": "h2",
|
|
"text": "Threads",
|
|
"id": "threads"
|
|
},
|
|
{
|
|
"level": "h2",
|
|
"text": "Capabilities",
|
|
"id": "capabilities"
|
|
},
|
|
{
|
|
"level": "h2",
|
|
"text": "Configuration reference (Matrix)",
|
|
"id": "configuration-reference-(matrix)"
|
|
}
|
|
],
|
|
"url": "llms-txt#matrix-(plugin)",
|
|
"links": []
|
|
} |