Clawd
df98d3ef95
- 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
165 lines
4.1 KiB
Markdown
165 lines
4.1 KiB
Markdown
# 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
|