Home Assistant Skill für OpenClaw

Überblick über den OpenClaw Home Assistant Skill

Der Home Assistant Skill verbindet OpenClaw mit Ihrer Home Assistant-Instanz und verwandelt Ihren KI-Agenten in einen leistungsstarken Smart-Home-Controller. Anstatt Dashboards zu navigieren oder YAML-Konfigurationsdateien zu bearbeiten, können Sie Ihr gesamtes Smart Home über natürliche Sprache verwalten — Lichter umschalten, Sensordaten prüfen, Automatisierungen erstellen und Geräteprobleme beheben, alles aus Ihrem Terminal.

Home Assistant ist die weltweit größte Open-Source-Heimautomatisierungsplattform mit Unterstützung für über 2.000 Integrationen mit Geräten von Philips Hue, Zigbee, Z-Wave, Matter und Hunderten weiteren. Der OpenClaw Home Assistant Skill nutzt die Home Assistant REST API, um Ihrem Agenten direkten Zugriff auf Entitäten, Dienste, Automatisierungen und Skripte auf Ihrer Instanz zu geben.

Typischer Workflow:

1. Bitten Sie OpenClaw, alle Wohnzimmerlichter auszuschalten und den Thermostat auf 20°C einzustellen.
2. Der Agent ruft die Home Assistant API auf, identifiziert die relevanten Entitäten und führt die Dienstaufrufe aus.
3. Die Bestätigung erfolgt sofort — kein Öffnen der Home Assistant App oder des Dashboards erforderlich.

Dieser Skill ist ideal für Entwickler, die bereits Home Assistant betreiben und schnelleren, skriptbaren Zugriff auf ihr Smart Home wünschen. Er lässt sich gut mit dem Slack-Skill kombinieren, um Smart-Home-Benachrichtigungen an Ihre Team-Kanäle zu senden, und integriert sich natürlich in Docker-basierte Deployments, wenn Sie Home Assistant in einem Container betreiben.

Voraussetzungen für den Home Assistant Skill

Bevor Sie den Home Assistant Skill installieren, stellen Sie sicher, dass Sie Folgendes haben:

• OpenClaw installiert und ausgeführt (v1.0+)
• Eine Home Assistant-Instanz (v2023.1+), die über das Netzwerk erreichbar ist — Installationsanleitung
• Einen langlebigen Zugriffstoken, der über Ihr Home Assistant-Profil generiert wurde
• Netzwerkzugriff von Ihrem Rechner zur Home Assistant-Instanz (lokal oder remote)
• clawhub CLI installiert für die Skill-Verwaltung

Überprüfen Sie Ihre Einrichtung:

# OpenClaw-Version prüfen
openclaw --version

# Home Assistant API-Konnektivität testen
curl -s -H "Authorization: Bearer YOUR_TOKEN" \
  http://YOUR_HA_HOST:8123/api/ | head -1

# clawhub CLI prüfen
clawhub --version

Wenn die API {"message": "API running."} zurückgibt, ist Ihre Home Assistant-Instanz bereit.

So installieren Sie den Home Assistant Skill

Installieren Sie den Home Assistant Skill mit einem einzigen Befehl:

npx clawhub@latest install home-assistant

Um die Installation zu überprüfen:

clawhub list

Sie sollten home-assistant in der Liste der installierten Skills sehen. Installieren Sie mit clawhub CLI für die schnellste Einrichtung.

Home Assistant Skill Konfiguration

Der Skill benötigt eine Home Assistant URL und einen langlebigen Zugriffstoken zur Authentifizierung von API-Anfragen.

Langlebigen Zugriffstoken generieren

1. Öffnen Sie Ihr Home Assistant Dashboard unter http://YOUR_HA_HOST:8123.
2. Klicken Sie auf Ihr Profilsymbol (untere linke Ecke).
3. Scrollen Sie zu Langlebige Zugriffstoken und klicken Sie auf Token erstellen.
4. Benennen Sie ihn openclaw-agent und kopieren Sie den generierten Token.

Umgebungsvariablen einrichten

Setzen Sie die folgenden Umgebungsvariablen:

# Home Assistant Instanz-URL (Port angeben, falls nicht Standard)
export HOMEASSISTANT_URL="http://192.168.1.100:8123"

# Langlebiger Zugriffstoken
export HOMEASSISTANT_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6..."

Sie können diese zu Ihrem Shell-Profil (~/.bashrc, ~/.zshrc) hinzufügen oder eine .env-Datei mit einem Geheimnis-Manager verwenden.

Wichtig: Hardcodieren Sie niemals Token in Konfigurationsdateien und committen Sie diese nicht in die Versionskontrolle. Verwenden Sie Umgebungsvariablen oder einen dedizierten Geheimnis-Manager wie 1Password.

Optional: Fernzugriff

Wenn sich Ihre Home Assistant-Instanz nicht im selben Netzwerk befindet, konfigurieren Sie den Fernzugriff über:

| Methode | Beschreibung | |---------|--------------| | Nabu Casa | Home Assistant Cloud — einfachste Option, stellt eine Remote-URL bereit | | Reverse Proxy | Nginx oder Caddy mit SSL-Terminierung | | Tailscale/WireGuard | VPN-Tunnel für sicheren LAN-ähnlichen Zugriff |

Home Assistant Skill Anwendungsbeispiele

1. Lichter und Geräte steuern

Du: „Schalte alle Lichter im Schlafzimmer aus und stelle die Wohnzimmerhelligkeit auf 40%."

Der Agent ruft light.turn_off für Schlafzimmer-Entitäten und light.turn_on mit brightness_pct: 40 für Wohnzimmerlichter auf. Er identifiziert Entitäten anhand der Raumzuordnung und gibt eine Bestätigungszusammenfassung zurück.

2. Sensordaten abfragen

Du: „Wie ist die aktuelle Temperatur im Büro und der gesamte Energieverbrauch heute?"

Der Agent fragt die Entitäten sensor.office_temperature und sensor.energy_daily ab und gibt formatierte Messwerte zurück: „Bürotemperatur: 22,3°C. Heutiger Energieverbrauch: 14,7 kWh." Er übernimmt Einheitenumrechnungen und formatiert Daten für die Lesbarkeit.

3. Eine Automatisierung erstellen

Du: „Erstelle eine Automatisierung, die das Verandalicht bei Sonnenuntergang einschaltet und es jeden Abend um 23 Uhr ausschaltet."

Der Agent erstellt eine Home Assistant-Automatisierung mit dem sun-Trigger für Sonnenuntergang und einem time-Trigger für 23:00. Er registriert die Automatisierung über die API, weist einen beschreibenden Namen zu und bestätigt, dass sie aktiviert ist.

4. Szenen aktivieren

Du: „Aktiviere die Filmabend-Szene."

Der Agent ruft scene.turn_on für scene.movie_night auf, wodurch die Lichter gedimmt, die Jalousien geschlossen und der Mediaplayer auf den richtigen Eingang eingestellt werden — alles gemäß Ihrer bestehenden Szenendefinition.

5. Gerätestatus beheben

Du: „Welche Geräte sind derzeit nicht verfügbar oder offline?"

Der Agent fragt alle Entitäten mit dem Status unavailable oder unknown ab, gruppiert sie nach Integration und gibt einen Diagnosebericht zurück: „3 Geräte offline — Zigbee-Bewegungssensor (zuletzt gesehen vor 2 Std.), Smarte Steckdose Küche (nicht erreichbar), Wetter-Integration (API-Timeout)."

Sicherheit & Best Practices

Befolgen Sie diese Richtlinien, um Ihr Smart Home sicher zu halten:

• Verwenden Sie minimale Berechtigungen. Erstellen Sie einen dedizierten Home Assistant-Benutzer für OpenClaw mit Berechtigungen, die auf die Räume und Geräte beschränkt sind, die der Agent steuern soll. Vermeiden Sie die Verwendung Ihres Admin-Konto-Tokens.
• Vor der Bestätigung überprüfen. Der Agent beschreibt, was er vorhat, bevor er destruktive Aktionen wie das Löschen von Automatisierungen oder das Deaktivieren von Integrationen ausführt. Überprüfen Sie immer die Aktionszusammenfassung.
• Token sicher aufbewahren. Langlebige Zugriffstoken bieten vollen API-Zugriff. Speichern Sie sie in Umgebungsvariablen, niemals in Klartextdateien. Rotieren Sie Token regelmäßig über Ihr Home Assistant-Profil.
• HTTPS verwenden. Wenn Sie remote auf Home Assistant zugreifen, verwenden Sie immer HTTPS mit einem gültigen SSL-Zertifikat. Setzen Sie Ihre Instanz niemals ohne Verschlüsselung dem öffentlichen Internet aus.
• Netzwerkzugriff einschränken. Beschränken Sie den API-Zugriff auf vertrauenswürdige IP-Bereiche mithilfe der ip_bans von Home Assistant oder Firewall-Regeln. Lesen Sie die Sicherheits-Checkliste für allgemeine OpenClaw-Sicherheitsrichtlinien.

Fehlerbehebung häufiger Fehler

„401 Unauthorized — Ungültiger Zugriffstoken"

Der langlebige Zugriffstoken ist ungültig oder abgelaufen.

1. Überprüfen Sie, ob der Token korrekt gesetzt ist:

echo $HOMEASSISTANT_TOKEN

2. Generieren Sie einen neuen Token über Ihre Home Assistant-Profilseite.
3. Stellen Sie sicher, dass keine zusätzlichen Leerzeichen oder Zeilenumbrüche im Token-Wert vorhanden sind.

„Connection refused — Home Assistant nicht erreichbar"

Der Agent kann keine Verbindung zu Ihrer Home Assistant-Instanz herstellen.

1. Überprüfen Sie, ob die URL korrekt ist und den Port enthält:

curl -s http://YOUR_HA_HOST:8123/api/

2. Prüfen Sie, ob Home Assistant läuft: sudo systemctl status homeassistant (für Supervised-Installationen).
3. Wenn Sie Docker verwenden, bestätigen Sie, dass der Container läuft: docker ps | grep homeassistant.
4. Überprüfen Sie die Firewall-Regeln — Port 8123 muss von Ihrem Rechner aus erreichbar sein.

„Entity not found — light.living_room"

Die Entitäts-ID stimmt mit keinem Gerät in Home Assistant überein.

1. Listen Sie alle verfügbaren Entitäten auf:

curl -s -H "Authorization: Bearer $HOMEASSISTANT_TOKEN" \
  http://YOUR_HA_HOST:8123/api/states | jq '.[].entity_id' | grep light

2. Entitäts-IDs unterscheiden Groß- und Kleinschreibung und verwenden Unterstriche — prüfen Sie auf Tippfehler.
3. Wenn das Gerät kürzlich hinzugefügt wurde, starten Sie Home Assistant neu, um die Entitätsregistrierung zu aktualisieren.