OpenClaw Matrix

https://docs.openclaw.ai/channels/matrix
Admin
OpenClaw Matrix is a channel plugin that integrates Matrix communication into OpenClaw, supporting...
Tokens:5,654
Snippets:64
Trust Score:5
Update:6 months ago
Show doc for...
Tokens:
Raw
### Matrix Plugin Interactive Setup Commands

Source: https://docs.openclaw.ai/channels/matrix

Commands to initiate the interactive setup wizard for the Matrix plugin.

```bash
openclaw channels add
openclaw configure --section channels
```

--------------------------------

### Install Matrix Plugin from Local Checkout

Source: https://docs.openclaw.ai/channels/matrix

Installs the Matrix plugin for OpenClaw from a local directory. Useful for development or custom builds.

```bash
openclaw plugins install ./path/to/local/matrix-plugin
```

--------------------------------

### Install Matrix Plugin via npm

Source: https://docs.openclaw.ai/channels/matrix

Installs the Matrix plugin for OpenClaw using npm. This is the recommended method for most users.

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

--------------------------------

### Multi-Account Matrix Configuration (JSON5)

Source: https://docs.openclaw.ai/channels/matrix

Example configuration for setting up multiple Matrix accounts within OpenClaw. This allows for distinct bot identities and configurations, such as different home servers, access tokens, and specific DM policies per account. It also shows how to set a default account for implicit routing.

```json5
{
  channels: {
    matrix: {
      enabled: true,
      defaultAccount: "assistant",
      dm: { policy: "pairing" },
      accounts: {
        assistant: {
          homeserver: "https://matrix.example.org",
          accessToken: "syt_assistant_xxx",
          encryption: true,
        },
        alerts: {
          homeserver: "https://matrix.example.org",
          accessToken: "syt_alerts_xxx",
          dm: {
            policy: "allowlist",
            allowFrom: ["@ops:example.org"],
          },
        },
      },
    },
  },
}
```

--------------------------------

### Minimal Token-Based Matrix Configuration

Source: https://docs.openclaw.ai/channels/matrix

Minimal configuration for the Matrix plugin using a homeserver URL and an access token. This is a common setup for bots.

```json
{
  "channels": {
    "matrix": {
      "enabled": true,
      "homeserver": "https://matrix.example.org",
      "accessToken": "syt_xxx",
      "dm": { "policy": "pairing" },
    }
  }
}
```

--------------------------------

### Matrix DM and Room Policy Configuration (JSON5)

Source: https://docs.openclaw.ai/channels/matrix

Example configuration for setting Matrix DM and group policies. It specifies an allowlist for direct messages and group interactions, restricting communication to specified Matrix IDs. This configuration also demonstrates how to set mention requirements for specific Matrix groups.

```json5
{
  channels: {
    matrix: {
      dm: {
        policy: "allowlist",
        allowFrom: ["@admin:example.org"],
      },
      groupPolicy: "allowlist",
      groupAllowFrom: ["@admin:example.org"],
      groups: {
        "!roomid:example.org": {
          requireMention: true,
        },
      },
    },
  },
}
```

--------------------------------

### Specify Matrix Account for CLI Commands

Source: https://docs.openclaw.ai/channels/matrix

In multi-account setups, specify which Matrix account to use for CLI commands using the `--account` flag. This is essential when managing multiple named accounts to ensure operations target the correct one. If no account is specified, the default account is used.

```bash
openclaw matrix verify status --account assistant
openclaw matrix verify backup restore --account assistant
openclaw matrix devices list --account assistant
```

--------------------------------

### Manage Matrix Room Key Backups (CLI)

Source: https://docs.openclaw.ai/channels/matrix

Manage room key backups for Matrix channels. Commands include checking backup status, restoring keys from server backup, and resetting the current server backup. Use `--verbose` for detailed diagnostics and `--json` for machine-readable output.

```bash
openclaw matrix verify backup status
openclaw matrix verify backup status --verbose
openclaw matrix verify backup restore
openclaw matrix verify backup restore --verbose
openclaw matrix verify backup reset --yes
```

--------------------------------

### Bootstrap Matrix Cross-Signing and Verification (CLI)

Source: https://docs.openclaw.ai/channels/matrix

Bootstrap the cross-signing and verification state for Matrix accounts. This command can be used with `--verbose` for detailed output, `--force-reset-cross-signing` to reset the identity, and `--json` for programmatic use. It's a critical step for setting up secure Matrix communication.

```bash
openclaw matrix verify bootstrap
openclaw matrix verify bootstrap --verbose
openclaw matrix verify bootstrap --force-reset-cross-signing
```

--------------------------------

### Bootstrap Encrypted Matrix Account

Source: https://docs.openclaw.ai/channels/matrix

Repairs and sets up an encrypted Matrix account by bootstrapping secret storage, cross-signing, and room-key backups. It handles interactive authentication challenges from the homeserver.

```bash
openclaw matrix verify bootstrap
```

--------------------------------

### Matrix Pairing Commands (Bash)

Source: https://docs.openclaw.ai/channels/matrix

Commands for managing Matrix user pairings with OpenClaw. `openclaw pairing list matrix` lists pending pairings, while `openclaw pairing approve matrix <CODE>` approves a pairing using a provided code. This facilitates secure connections between users and the OpenClaw bot.

```bash
openclaw pairing list matrix
```

```bash
openclaw pairing approve matrix <CODE>
```

--------------------------------

### Verify Matrix Device with Recovery Key (CLI)

Source: https://docs.openclaw.ai/channels/matrix

Verify a specific Matrix device using a recovery key. This command can be run with `--verbose` for detailed information. It's used to ensure the authenticity of devices participating in Matrix communication.

```bash
openclaw matrix verify device "<your-recovery-key>"
openclaw matrix verify device "<your-recovery-key>" --verbose
```

--------------------------------

### Enable Matrix Channel Encryption

Source: https://docs.openclaw.ai/channels/matrix

Enable and configure encryption for Matrix channels. This includes setting the homeserver URL, providing an access token, and defining the direct message policy. Encryption is crucial for secure communication.

```json
{
  "channels": {
    "matrix": {
      "enabled": true,
      "homeserver": "https://matrix.example.org",
      "accessToken": "syt_xxx",
      "encryption": true,
      "dm": {
        "policy": "pairing"
      }
    }
  }
}
```

--------------------------------

### Check Matrix Verification Status (CLI)

Source: https://docs.openclaw.ai/channels/matrix

Check the verification status of the Matrix client. This command can be run with a `--verbose` flag for detailed diagnostics and `--json` for machine-readable output. It is essential for ensuring secure connections and device verification.

```bash
openclaw matrix verify status
openclaw matrix verify status --verbose
openclaw matrix verify status --include-recovery-key --json
```

--------------------------------

### Enable Streaming Previews for Matrix Channel

Source: https://docs.openclaw.ai/channels/matrix

This configuration snippet enables partial streaming previews for Matrix messages in OpenClaw. When enabled, OpenClaw sends a single draft reply that is edited in place as the model generates text, offering a more dynamic user experience.

```json5
{
  channels: {
    matrix: {
      streaming: "partial",
    },
  },
}
```

--------------------------------

### Password-Based Matrix Configuration

Source: https://docs.openclaw.ai/channels/matrix

Configuration for the Matrix plugin using a homeserver URL, user ID, and password. The token is cached after the initial login.

```json
{
  "channels": {
    "matrix": {
      "enabled": true,
      "homeserver": "https://matrix.example.org",
      "userId": "@bot:example.org",
      "password": "replace-me", 
      "deviceName": "OpenClaw Gateway"
    }
  }
}
```

--------------------------------

### Configure Matrix Channel with DM Pairing and E2EE

Source: https://docs.openclaw.ai/channels/matrix

This JSON configuration enables the Matrix channel in OpenClaw, sets up DM pairing, enforces a room allowlist, and enables end-to-end encryption (E2EE). It specifies homeserver details, access token, and group policies.

```json5
{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_xxx",
      encryption: true,

      dm: {
        policy: "pairing",
      },

      groupPolicy: "allowlist",
      groupAllowFrom: ["@admin:example.org"],
      groups: {
        "!roomid:example.org": {
          requireMention: true,
        },
      },

      autoJoin: "allowlist",
      autoJoinAllowlist: ["!roomid:example.org"],
      threadReplies: "inbound",
      replyToMode: "off",
      streaming: "partial",
    },
  },
}
```

--------------------------------

### Manage Matrix Backup and Verification

Source: https://docs.openclaw.ai/channels/matrix

A sequence of commands to reset the room-key backup, check its status, and then verify the Matrix device status. This is useful for ensuring future encrypted messages work while accepting the loss of old history.

```bash
openclaw matrix verify backup reset --yes
openclaw matrix verify backup status --verbose
openclaw matrix verify status
```

--------------------------------

### Configure Bot-to-Bot Matrix Communication

Source: https://docs.openclaw.ai/channels/matrix

Configure Matrix channels to allow or disallow messages from other bots. The `allowBots` setting can be set to `true` to accept all messages or `"mentions"` to accept only messages that mention the bot. Room-specific settings can override the global configuration. Messages from the same user ID are always ignored to prevent loops.

```json
{
  "channels": {
    "matrix": {
      "allowBots": "mentions",
      "groups": {
        "!roomid:example.org": {
          "requireMention": true
        }
      }
    }
  }
}
```

--------------------------------

### Configure Private Matrix Homeserver Access

Source: https://docs.openclaw.ai/channels/matrix

Enables connectivity to internal or LAN-based Matrix homeservers by setting the allowPrivateNetwork flag. This is required to bypass default SSRF protections for trusted internal infrastructure.

```json5
{
  channels: {
    matrix: {
      homeserver: "http://matrix-synapse:8008",
      allowPrivateNetwork: true,
      accessToken: "syt_internal_xxx",
    },
  },
}
```

```bash
openclaw matrix account add \
  --account ops \
  --homeserver http://matrix-synapse:8008 \
  --allow-private-network \
  --access-token syt_ops_xxx
```

--------------------------------

### Configure Matrix Outbound Proxy

Source: https://docs.openclaw.ai/channels/matrix

Sets an explicit HTTP(S) proxy for Matrix traffic to route requests through a specific gateway. This configuration applies to both runtime traffic and account status probes.

```json5
{
  channels: {
    matrix: {
      homeserver: "https://matrix.example.org",
      accessToken: "syt_bot_xxx",
      proxy: "http://127.0.0.1:7890",
    },
  },
}
```

--------------------------------

### Check Matrix Device Verification Status

Source: https://docs.openclaw.ai/channels/matrix

Displays the trust signals for a Matrix device, indicating local trust, cross-signing verification, and if it's signed by the owner. Local trust alone is insufficient for full verification by OpenClaw.

```bash
openclaw matrix verify status --verbose
```

--------------------------------

### Force Reset Cross-Signing Identity

Source: https://docs.openclaw.ai/channels/matrix

Use this command with caution to intentionally discard the current Matrix cross-signing identity and create a new one. This is a destructive operation.

```bash
openclaw matrix verify --force-reset-cross-signing
```

--------------------------------

### Reset Matrix Room-Key Backup

Source: https://docs.openclaw.ai/channels/matrix

Resets the server-side room-key backup, allowing for a new backup baseline for future encrypted messages. This action will make old encrypted history unrecoverable.

```bash
openclaw matrix verify backup reset --yes
```
Tokens:
Raw