# Matrix Plugin

## Overview

OpenClaw integrates with Matrix, an open, decentralized messaging protocol. The plugin enables bot connectivity as a standard user account on any homeserver, supporting direct messaging, group rooms, threads, and encrypted communications.

## Installation

The Matrix functionality ships as a separate plugin requiring explicit installation via npm registry or local checkout from a git repository.

```bash
openclaw plugins install @openclaw/matrix
```

## Key Features

The implementation provides comprehensive messaging capabilities including:

- Direct message exchanges and room participation
- Thread-based conversations
- Media file handling
- End-to-end encryption using Rust crypto SDK
- Reaction and poll functionality
- Geographic location sharing

## Authentication Setup

Users must create a Matrix account and obtain an access token. The documentation provides curl command examples for retrieving tokens via the Matrix login API, with options to supply credentials directly or store them as environment variables.

## Encryption (E2EE)

When enabled, the system handles encrypted room decryption automatically upon crypto module loading. Device verification through another Matrix client establishes trust for key sharing.

If the crypto module fails to load, encrypted rooms remain inaccessible with appropriate logging warnings.

## Access Controls

### DMs

Default pairing policy requires approval codes for unknown senders.

### Rooms

Mention-gating enabled by default; allowlist configuration restricts bot triggering to specified rooms and users.

## Threading & Configuration

Reply behavior customizes through `threadReplies` settings:

- `off` - No threading
- `inbound` - Thread replies to threaded messages
- `always` - Always use threads

Text output splits based on character limits or paragraph boundaries.
