OpenClaw + Matrix

Prerequisites

• OpenClaw running (see our deployment guide)
• A Matrix account (on any homeserver, e.g., matrix.org)
• An access token for your bot account

Step 1: Create a Matrix Account

If you don't have a Matrix account:

1. Visit app.element.io or your preferred Matrix client
2. Click Create Account
3. Choose a homeserver (matrix.org is the default)
4. Complete registration

Pro tip: Create a dedicated account for your OpenClaw bot rather than using your personal account.

Step 2: Get Your Access Token

1. Log in to Element (or your Matrix client)
2. Go to Settings → Help & About
3. Scroll to Advanced → click Access Token
4. Copy the token

Alternatively, use curl to get a token:

curl -XPOST "https://matrix.org/_matrix/client/r0/login" -d '{"type":"m.login.password", "user":"your-username", "password":"your-password"}'

Configuration

Add the Matrix channel to your OpenClaw config:

# In your openclaw config
channels:
  matrix:
    enabled: true
    homeserver: "https://matrix.org"
    access_token: "YOUR_ACCESS_TOKEN"
    device_id: "OPENCLAW_BOT"

Or via environment variables in your docker-compose.yml:

environment:
  - MATRIX_ENABLED=true
  - MATRIX_HOMESERVER=https://matrix.org
  - MATRIX_ACCESS_TOKEN=YOUR_ACCESS_TOKEN
  - MATRIX_DEVICE_ID=OPENCLAW_BOT

Step 3: Restart OpenClaw

docker compose restart openclaw

Verification

1. Open Element or your Matrix client
2. Start a direct message with your bot account
3. Send a message — OpenClaw should respond

Check logs for connection status:

docker compose logs -f openclaw | grep -i matrix

Common Issues

Access token invalid: Tokens can expire or be revoked. Generate a new token and update your config.

Homeserver URL: Make sure to use the correct homeserver URL (e.g., https://matrix.org, not matrix.org). Some homeservers use different URLs.

Rate limiting: Matrix homeservers may rate-limit messages. If you see 429 errors, reduce message frequency or contact your homeserver admin.

Encryption: Encrypted rooms (E2EE) require additional setup. For testing, use unencrypted rooms first.