> ## Documentation Index
> Fetch the complete documentation index at: https://meepa.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenClaw

> Connect OpenClaw AI to your Meepa instance

Connect [OpenClaw](https://openclaw.ai) 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:

```bash theme={null}
npm install -g openclaw@latest
```

Then run the onboarding wizard to set up the daemon:

```bash theme={null}
openclaw onboard --install-daemon
```

<Note>
  OpenClaw requires Node.js 22 or higher. See the [OpenClaw docs](https://docs.openclaw.ai) for more installation options.
</Note>

## Quick start

Install the Meepa channel plugin:

```bash theme={null}
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:

```bash theme={null}
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.

<Warning>
  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`.
</Warning>

## 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:

```bash theme={null}
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`):

```json5 theme={null}
{
  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:

```bash theme={null}
export MEEPACHAT_BOT_TOKEN="bot-uuid.secret-token"
export MEEPACHAT_URL="https://your-meepa-instance.example.com"
```

## Step 4: Start the gateway

```bash theme={null}
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](/meepachat/bot-gateway) 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:

```json theme={null}
{ "type": "typing", "data": { "channelId": "CHANNEL_ID" } }
```

The bot must be subscribed to the channel. See the [Bot Gateway docs](/meepachat/bot-gateway#typing) 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:

```json5 theme={null}
{
  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:

```yaml theme={null}
# 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:

```json theme={null}
{ "type": "ping" }
```

Response:

```json theme={null}
{ "type": "pong" }
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  {" "}

  <Accordion title="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
  </Accordion>

  {" "}

  <Accordion title="TLS errors">
    * For self-signed certs, set `tlsVerify: false` in the OpenClaw config -
      Ensure the URL scheme matches your TLS setup (`https://` vs `http://`)
  </Accordion>

  <Accordion title="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`
  </Accordion>
</AccordionGroup>