MQTT → Clawdbot Bridge

Subscribe to MQTT topics and forward messages to Clawdbot via webhook.

Perfect for triggering your AI assistant from Home Assistant, IoT devices, or any MQTT-enabled system — without exposing your Clawdbot gateway to the internet.

How It Works

[Your Device] → [MQTT Broker] → [This Bridge] → [Clawdbot Webhook] → [AI Response]

The bridge runs locally alongside Clawdbot, subscribes to MQTT topics, and calls the local webhook endpoint when messages arrive.

Quick Start

1. Install

git clone https://gitea.olex.me/olex/mqtt-clawdbot-bridge.git
cd mqtt-clawdbot-bridge
npm install

2. Configure

cp .env.example .env
# Edit .env with your settings

Required settings:

• MQTT_URL — Your MQTT broker (e.g., mqtt://192.168.1.100:1883)
• CLAWDBOT_TOKEN — Webhook token from your Clawdbot config

3. Enable Clawdbot Webhooks

Add to your ~/.clawdbot/clawdbot.json:

{
  "hooks": {
    "enabled": true,
    "token": "your-secret-token",
    "path": "/hooks"
  }
}

Restart the gateway: clawdbot gateway restart

4. Run

npm start

Configuration

All configuration is via environment variables (or .env file):

Variable	Default	Description
MQTT_URL	mqtt://localhost:1883	MQTT broker URL
MQTT_USERNAME	—	MQTT username (optional)
MQTT_PASSWORD	—	MQTT password (optional)
MQTT_TOPICS	clawd/#	Comma-separated topics to subscribe
MQTT_CLIENT_ID	random	MQTT client identifier
CLAWDBOT_URL	http://127.0.0.1:18789	Clawdbot gateway URL
CLAWDBOT_TOKEN	—	Webhook token (required)
CLAWDBOT_MODE	wake	wake (system event) or agent (isolated run)
LOG_LEVEL	info	debug, info, warn, error

Webhook Modes

wake (default)

Triggers a system event in the main session. Good for alerts and notifications that should appear in your regular chat context.

agent

Runs an isolated agent session. Good for tasks that need a dedicated response without cluttering main chat history.

Running as a Service

systemd (Linux)

# Copy files
sudo cp -r . /opt/mqtt-clawdbot-bridge
sudo cp mqtt-clawdbot-bridge.service /etc/systemd/system/

# Configure
sudo cp .env.example /opt/mqtt-clawdbot-bridge/.env
sudo nano /opt/mqtt-clawdbot-bridge/.env

# Enable and start
sudo systemctl daemon-reload
sudo systemctl enable mqtt-clawdbot-bridge
sudo systemctl start mqtt-clawdbot-bridge

# Check status
sudo systemctl status mqtt-clawdbot-bridge
journalctl -u mqtt-clawdbot-bridge -f

Home Assistant Example

Publish to MQTT when a door opens:

automation:
  - alias: "Notify Clawd - Front Door"
    trigger:
      - platform: state
        entity_id: binary_sensor.front_door
        to: "on"
    action:
      - service: mqtt.publish
        data:
          topic: "clawd/alerts/door"
          payload: "Front door opened at {{ now().strftime('%H:%M') }}"

Or send JSON with more context:

    action:
      - service: mqtt.publish
        data:
          topic: "clawd/alerts/motion"
          payload: >
            {"message": "Motion detected in {{ trigger.to_state.attributes.friendly_name }}", 
             "entity": "{{ trigger.entity_id }}",
             "time": "{{ now().isoformat() }}"}

Message Format

The bridge accepts:

• Plain text: Forwarded as-is
• JSON with message/text/payload field: That field is extracted and forwarded

Messages are prefixed with the topic for context:

[MQTT clawd/alerts/door] Front door opened at 10:30

Troubleshooting

Bridge can't connect to MQTT

• Check broker URL and credentials
• Verify network connectivity: mosquitto_sub -h <broker> -t '#'

Messages not reaching Clawdbot

• Verify CLAWDBOT_TOKEN matches your gateway config
• Check gateway is running: clawdbot gateway status
• Enable debug logging: LOG_LEVEL=debug npm start

Webhook returns 401

• Token mismatch — check hooks.token in Clawdbot config matches CLAWDBOT_TOKEN

License

MIT