@turquoisebay/mqtt

MQTT channel plugin for OpenClaw — bidirectional messaging via MQTT brokers.

Features

• 🔌 Bidirectional messaging — subscribe and publish to MQTT topics
• 🔁 Robust reconnection — recovers from broker restarts and cold starts
• 🔒 TLS support — secure connections to cloud brokers
• ⚡ QoS levels — configurable delivery guarantees (0, 1, 2)

Installation

openclaw plugins install @turquoisebay/mqtt

Or manually:

git clone https://github.com/hughmadden/openclaw-mqtt ~/.openclaw/extensions/mqtt
cd ~/.openclaw/extensions/mqtt && npm install

Configuration

Add to ~/.openclaw/openclaw.json:

{
  channels: {
    mqtt: {
      brokerUrl: "mqtt://localhost:1883",
      // Optional auth
      username: "openclaw",
      password: "secret",
      // Topics
      topics: {
        inbound: "openclaw/inbound",   // Subscribe to this
        outbound: "openclaw/outbound"  // Publish responses here
      },
      // Quality of Service (0=fire-and-forget, 1=at-least-once, 2=exactly-once)
      qos: 1
    }
  }
}

Then restart the gateway:

openclaw gateway restart

Usage

Sessions & correlation IDs (important)

• Sessions are keyed by senderId → OpenClaw uses mqtt:{senderId} as the SessionKey, so memory and conversation history are grouped by sender.
• correlationId is request‑level only → if you include it in inbound JSON, it’s echoed back in the outbound reply for client-side matching. It does not create a new session or change memory.

If you want separate conversations, use distinct senderIds.

Receiving messages (inbound)

Messages published to your inbound topic will be processed by OpenClaw. You can send either plain text or JSON (recommended):

# Plain text
mosquitto_pub -t "openclaw/inbound" -m "Alert: Service down on playground"

# JSON (recommended)
mosquitto_pub -t "openclaw/inbound" -m '{"senderId":"pg-cli","text":"hello","correlationId":"abc-123"}'

Sending messages (outbound)

Agent replies are published to the outbound topic as JSON:

{"senderId":"openclaw","text":"...","kind":"final","ts":1700000000000}

If you want to publish custom text via CLI, use the message tool:

openclaw agent --message "Send MQTT: Temperature is 23°C"

Security

Important: Any client that can publish to the inbound topic has full access to your OpenClaw agent. Treat MQTT as a trusted channel only (restricted broker, auth, private network). If you need untrusted access, add a validation layer before publishing to openclaw/inbound.

Development

# Clone (replace with your host)
git clone ssh://<host>/opt/git/openclaw-mqtt.git
cd openclaw-mqtt

# Install deps
npm install

# Run tests
npm test

# Type check
npm run typecheck

# Build
npm run build

Architecture

MQTT Broker (Mosquitto/EMQX)
     │
     ├─► inbound topic ──► OpenClaw Gateway ──► Agent
     │
     └─◄ outbound topic ◄── OpenClaw Gateway ◄── Agent

License

MIT © Hugh Madden

See Also

• OpenClaw — The AI assistant platform
• MQTT.js — MQTT client library
• Mosquitto — Popular MQTT broker