OpenClaw

Connect OpenClaw AI to your Meepa instance

Connect OpenClaw to your self-hosted Meepa instance so your AI assistant can read and send messages across your servers.

Overview

Meepa exposes a Bot API that OpenClaw connects to as a channel plugin. The integration uses:

• Bot Gateway WebSocket (/api/bot-gateway) for receiving real-time events
• REST API for sending messages, reactions, and other actions
• Bot token authentication (Authorization: Bot <token>)

Prerequisites

• A running Meepa instance accessible from your OpenClaw host
• Admin or owner role on the Meepa server you want to connect
• OpenClaw installed and running (see below)

Install OpenClaw

If you don’t have OpenClaw yet, install it globally:

npm install -g openclaw@latest

Then run the onboarding wizard to set up the daemon:

openclaw onboard --install-daemon

OpenClaw requires Node.js 22 or higher. See the OpenClaw docs for more installation options.

Quick start

Install the Meepa channel plugin:

openclaw plugins install @meepa/openclaw

Step 1: Create a bot

Create a bot in Meepa to act as the OpenClaw connection. Go to Server Settings → Bots → Create Bot or use the CLI:

meepachat bots create --username openclaw --server SERVER_ID --display-name "OpenClaw"

Save the bot token from the response — you’ll need it for OpenClaw configuration.

Treat bot tokens like passwords. Never commit them to source control or expose them in client-side code. Regenerate compromised tokens with meepachat bots regenerate-token BOT_ID.

Step 2: Add the bot to servers and channels

The bot is automatically added to the server specified during creation. To add it to additional servers, go to My Bots → Select Bot → Add to Server or use the CLI:

meepachat bots add-to-server BOT_ID --server SERVER_ID

Then add the bot to the channels you want it to respond in. Open the channel, click Manage Members, and add the bot. The bot only receives messages from channels it’s a member of.

Step 3: Configure OpenClaw

Add the Meepa channel to your OpenClaw configuration file (config.json or config.json5):

{
  channels: {
    meepachat: {
      enabled: true,

      // Your Meepa instance URL (required)
      url: "https://your-meepa-instance.example.com",

      // Bot token from Step 1 (recommended: use env var)
      token: "$MEEPACHAT_BOT_TOKEN",

      // TLS verification (default: true)
      // Set to false for self-signed certificates
      tlsVerify: true,
    },
  },
}

Environment variables

Set the bot token as an environment variable instead of putting it in the config:

export MEEPACHAT_BOT_TOKEN="bot-uuid.secret-token"
export MEEPACHAT_URL="https://your-meepa-instance.example.com"

Step 4: Start the gateway

openclaw gateway start

OpenClaw will:

1. Connect to wss://your-meepa-instance.example.com/api/bot-gateway?token=<bot-token>
2. Receive a ready event with the bot’s user info, servers, and channels
3. Auto-subscribe to all channels the bot has access to
4. Begin receiving real-time events

You should see in the logs:

[meepachat] Connected to your-meepa-instance.example.com
[meepachat] Bot "openclaw" ready - 1 server, 5 channels

How it works

Inbound (Meepa -> OpenClaw)

The bot connects to Meepa’s Bot Gateway WebSocket and receives events:

Event	Description
ready	Connection established, includes user info and server list
message.created	New message in a subscribed channel
message.updated	Message was edited
message.deleted	Message was deleted
reaction.sync	Reactions changed on a message
typing	A user is typing in a subscribed channel

Typing Indicators

The plugin can send typing indicators over the WebSocket so other users see the bot as “typing” while it generates a response:

{ "type": "typing", "data": { "channelId": "CHANNEL_ID" } }

The bot must be subscribed to the channel. See the Bot Gateway docs for details.

Outbound (OpenClaw -> Meepa)

The plugin sends responses via Meepa’s REST API:

Action	Method	Endpoint
Send message	POST	/api/servers/{serverId}/channels/{channelId}/messages
Reply in thread	POST	Same endpoint with threadId in body
Add reaction	PUT	/api/messages/{messageId}/reactions/{emoji}
Remove reaction	DELETE	/api/messages/{messageId}/reactions/{emoji}
Upload file	POST	/api/upload

All requests use:

Authorization: Bot <token>

Self-hosted considerations

Network access

OpenClaw must be able to reach your Meepa instance over the network:

Setup	URL Example	Notes
Same machine	http://localhost:8091	No TLS needed
Local network	http://192.168.1.50:8091	Use IP or local DNS
Tailscale	https://chat.your-tailnet	Both hosts on Tailscale
Public domain	https://chat.example.com	Needs valid TLS cert
Docker network	http://meepachat:8091	Same compose stack

Self-signed certificates

If your Meepa instance uses a self-signed or private CA certificate:

{
  channels: {
    meepachat: {
      url: "https://chat.internal",
      token: "$MEEPACHAT_BOT_TOKEN",
      tlsVerify: false,
    },
  },
}

Running in Docker

If both OpenClaw and Meepa run in Docker, add OpenClaw to Meepa’s network:

# docker-compose.yml (OpenClaw)
services:
  openclaw:
    image: openclaw/openclaw
    environment:
      MEEPACHAT_URL: http://meepachat:8091
      MEEPACHAT_BOT_TOKEN: "bot-uuid.secret-token"
    networks:
      - meepachat_default

networks:
  meepachat_default:
    external: true

WebSocket keepalive

The Bot Gateway sends WebSocket pings every 30 seconds. The plugin must respond with pong frames (handled automatically by most WebSocket libraries). If no pong is received within 60 seconds, the connection is closed.

The plugin can also send application-level pings:

{ "type": "ping" }

Response:

{ "type": "pong" }

Troubleshooting

Bot connects but doesn't receive messages

• Verify the bot has been added to the server: meepachat bots servers BOT_ID
• Check that the bot is a member of the expected channels (it auto-joins on server add)
• Ensure the bot is a member of the channels you expect it to respond in

Connection refused / timeout

• Verify the Meepa URL is reachable: curl https://your-meepa-instance.example.com/api/health - Check firewall rules and Tailscale ACLs if applicable - If using Docker, ensure containers are on the same network

TLS errors

• For self-signed certs, set tlsVerify: false in the OpenClaw config - Ensure the URL scheme matches your TLS setup (https:// vs http://)

Bot token invalid

• Tokens have the format BOT_ID.SECRET — ensure you copied the full value
• Regenerate if needed: meepachat bots regenerate-token BOT_ID