# 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