home-assistant — OpenClaw Skill

An OpenClaw skill that turns your AI assistant into a smart home controller. Deploy Home Assistant Container on any Linux server in one command, then let your AI manage devices, read sensors, and control climate — just by asking.

"Turn on the AC at 20°C" → done. "What's the humidity?" → answered. "Turn it off." → done.

---

What you can do

Once set up, your AI assistant can:

• Control any smart home device — turn things on/off, change settings, check status
• Read live sensor data — temperature, humidity, power consumption, presence
• Manage your AC — power, target temperature in °C (auto-converts for SmartThings which reports in °F), fan mode, swing
• List all connected devices — query every entity in Home Assistant by name or type
• Keep Home Assistant running — start, stop, restart, update, tail logs, validate config — all without touching the server manually
• Stay secure — API token-based auth, port 8123 blocked from internet, SSH tunnel for UI access

The skill ships with a control script (ha-ctl.sh) that the AI calls directly. No browser required for day-to-day use.

---

Requirements

• Linux server (Ubuntu 20.04+ / Debian 11+) with root access
• OpenClaw installed
• Internet connection (to pull the Docker image)

---

Installation

Copy the skill into your OpenClaw workspace:

cp -r home-assistant/ ~/.openclaw/workspace/skills/

Or unpack from the .skill file:

unzip home-assistant.skill -d ~/.openclaw/workspace/skills/home-assistant

---

Setup

1. Deploy Home Assistant

sudo bash skills/home-assistant/scripts/setup.sh

This single script:

• Installs Docker CE (skips if already present)
• Creates /opt/homeassistant/config/
• Drops in a production-ready docker-compose.yml (host network, privileged, auto-restart)
• Copies a base configuration.yaml (metric units, default_config: for UI-based integrations)
• Pulls ghcr.io/home-assistant/home-assistant:stable and starts the container
• Waits for HA to be reachable on port 8123

2. Complete onboarding

Open http://<your-server-ip>:8123 and create your admin account. This is the only time you need the browser for basic setup.

3. Add integrations

In the HA UI: Settings → Devices & Services → Add Integration

Integration	What it connects	How to get credentials
SmartThings	Samsung ACs, TVs, presence sensors, SmartTags	PAT from account.smartthings.com/tokens
LG ThinQ	LG ACs, washing machines, fridges (v2 only)	PAT from connect-pat.lgthinq.com
Google Cast	Chromecast, Google Home speakers	Auto-discovered on local network
Met.no	Local weather forecast	Built-in, no key needed
HACS + SmartThinQ Sensors	LG v1 devices (older hardware)	ollo69/ha-smartthinq-sensors

SmartThings note: Temperatures are reported in °F regardless of HA locale. The ac and set-temp commands convert automatically so you always work in °C.

4. Generate an API token

Required for all device control commands. Run once after onboarding:

bash skills/home-assistant/scripts/ha-ctl.sh gen-token <refresh_token>

The refresh token can be found in /opt/homeassistant/config/.storage/auth or created via the HA UI under Profile → Long-Lived Access Tokens. The token is stored at /opt/homeassistant/botler.token (chmod 600).

---

Command Reference

bash skills/home-assistant/scripts/ha-ctl.sh <command>

Container management

Command	Description
status	Container state, HA version, and API reachability
start	Start the container
stop	Stop the container
restart	Restart the container
update	Pull latest stable image and recreate container
logs	Last 100 log lines
follow	Live log stream (Ctrl+C to exit)
shell	Drop into bash inside the container
config-check	Run HA's built-in config validator before restarting

Device queries

Command	Description
devices	List all entities and their current state
devices <filter>	Filter by keyword (e.g. devices climate, devices sensor)
state <entity_id>	Full state + all attributes for a specific entity
ac	Quick status for the default AC (climate.ar_sala) in °C

Climate control

Command	Description
on [entity_id]	Turn on (default: climate.ar_sala)
off [entity_id]	Turn off (default: climate.ar_sala)
set-temp <°C> [entity_id]	Set target temperature in Celsius

Token management

Command	Description
gen-token <refresh_token>	Generate and store a long-lived API token

---

Examples

# Is everything running?
bash skills/home-assistant/scripts/ha-ctl.sh status

# What devices do I have?
bash skills/home-assistant/scripts/ha-ctl.sh devices

# AC status
bash skills/home-assistant/scripts/ha-ctl.sh ac
# → Ar Sala: COOL | Room: 26.0°C | Target: 23.0°C | Fan: auto

# Turn on and set temperature
bash skills/home-assistant/scripts/ha-ctl.sh on
bash skills/home-assistant/scripts/ha-ctl.sh set-temp 22

# Check a specific sensor
bash skills/home-assistant/scripts/ha-ctl.sh state sensor.ar_sala_humidity
# → State: 58 | unit_of_measurement: %

# Turn off
bash skills/home-assistant/scripts/ha-ctl.sh off

# Update HA to latest version
bash skills/home-assistant/scripts/ha-ctl.sh update

---

File Structure

home-assistant/
├── SKILL.md                     # OpenClaw skill definition (triggers + AI instructions)
├── README.md                    # This file
├── scripts/
│   ├── setup.sh                 # One-shot Docker + HA deployment
│   └── ha-ctl.sh                # Container management + REST API device control
└── assets/
    ├── docker-compose.yml       # HA Container config (host network, privileged, auto-restart)
    └── configuration.yaml       # Base HA config (metric, default_config, API enabled)

---

Security

Block port 8123 from the internet. HA only needs to be reachable from localhost — the control script calls http://localhost:8123 directly.

Enable a firewall and deny external access:

ufw default allow incoming   # safe default for existing servers
ufw deny 8123/tcp            # block HA from internet
ufw deny 18555/tcp           # block go2rtc (HA WebRTC component)
ufw --force enable

Access the UI when you need it via SSH tunnel — no port needs to be open:

ssh -L 8123:localhost:8123 root@your-server
# then open http://localhost:8123 in your browser

Additional notes:

• botler.token is gitignored — never commit it
• Token file is chmod 600 (root-only)
• HA runs with network_mode: host and privileged: true (required for device discovery and Bluetooth proxies)
• Long-lived tokens expire after 365 days — regenerate with gen-token

---

License

MIT