Initial commit: MQTT to Clawdbot bridge

- Subscribe to MQTT topics, forward to Clawdbot webhook - Configurable via environment variables - Supports wake (system event) and agent (isolated) modes - Includes systemd service template - Home Assistant examples in README
2026-01-28 10:09:25 +00:00
commit df98d3ef95
6 changed files with 396 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,164 @@
+# MQTT → Clawdbot Bridge
+
+Subscribe to MQTT topics and forward messages to [Clawdbot](https://github.com/clawdbot/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
+
+```bash
+git clone https://gitea.olex.me/olex/mqtt-clawdbot-bridge.git
+cd mqtt-clawdbot-bridge
+npm install
+```
+
+### 2. Configure
+
+```bash
+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`:
+
+```json
+{
+  "hooks": {
+    "enabled": true,
+    "token": "your-secret-token",
+    "path": "/hooks"
+  }
+}
+```
+
+Restart the gateway: `clawdbot gateway restart`
+
+### 4. Run
+
+```bash
+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)
+
+```bash
+# 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:
+
+```yaml
+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:
+
+```yaml
+    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