FeaturesHow it worksFAQSign inTry it free

Documentation

Device Connection & IoT Bridge API

Connect your OpenClaw agent to smart home devices via MQTT, Zigbee, and Home Assistant. Quickstart, protocol reference, and device API.

Getting Started

The ClawTether bridge connects your OpenClaw agent to physical devices. Install the client, discover devices on your network, and start reading sensors or controlling hardware.

1. Install the Bridge

npm install -g @clawtether/bridge

2. Discover Devices

# Auto-discover Home Assistant, MQTT brokers, and Zigbee coordinators
clawtether discover
# Output:
# Found: Home Assistant at 192.168.1.50:8123
# Found: Mosquitto MQTT at 192.168.1.50:1883
# Found: Zigbee2MQTT (14 devices)

3. Connect to Home Assistant

# Connect with a long-lived access token
clawtether connect homeassistant \
--url http://192.168.1.50:8123 \
--token <HA_LONG_LIVED_TOKEN>

Supported Protocols

Home Assistant

Full support

WebSocket API. Read entities, call services, subscribe to state changes.

MQTT

Full support

Mosquitto, HiveMQ, EMQX. Pub/sub on any topic. QoS 0/1/2.

Zigbee

Via Zigbee2MQTT

ZHA and Z2M coordinators. Pair, read, and control Zigbee devices.

Matter

Beta

Thread and WiFi Matter devices. Discovery and basic control.

Device API

The bridge exposes a local REST API your OpenClaw agent uses to interact with devices.

List Connected Devices

GET /api/v1/devices
Response:
[{ "id": "light.living_room", "type": "light", "state": "on", "protocol": "homeassistant" },
{ "id": "sensor.temp_office", "type": "sensor", "state": "22.4", "protocol": "mqtt" }]

Read Device State

GET /api/v1/devices/:id/state
Response:
{ "state": "22.4", "unit": "°C", "last_updated": "2026-03-25T10:30:00Z" }

Control a Device

POST /api/v1/devices/:id/action
{
"action": "turn_on",
"params": { "brightness": 80, "color_temp": 4000 }
}

Subscribe to Events (MQTT)

POST /api/v1/subscriptions
{
"topic": "zigbee2mqtt/motion_sensor",
"callback": "http://localhost:3000/agent/webhook"
}

Device Permissions

  • Read-only — Agent can read sensor data but cannot control devices. Default for new connections.
  • Control — Agent can read and send commands (turn on/off, adjust brightness, set temperature).
  • Per-device ACL — Set read-only or control permissions individually per device or per room.
  • Action approval — Critical devices (locks, garage doors) require manual approval before the agent can act.

Ready to connect your agent to the physical world?

Try ClawTether free and connect the IoT bridge to your agent.

Try it free