Compétence Home Assistant pour OpenClaw

Présentation du skill Home Assistant pour OpenClaw

Le skill Home Assistant connecte OpenClaw à votre instance Home Assistant, transformant votre agent IA en un puissant contrôleur domotique. Au lieu de naviguer dans les tableaux de bord ou de modifier des fichiers de configuration YAML, vous pouvez gérer toute votre maison connectée en langage naturel — basculer les lumières, vérifier les relevés des capteurs, créer des automatisations et diagnostiquer les problèmes d'appareils, le tout depuis votre terminal.

Home Assistant est la plus grande plateforme open source d'automatisation domestique au monde, prenant en charge plus de 2 000 intégrations avec des appareils de Philips Hue, Zigbee, Z-Wave, Matter, et bien d'autres. Le skill Home Assistant pour OpenClaw exploite l'API REST de Home Assistant pour donner à votre agent un accès direct aux entités, services, automatisations et scripts exécutés sur votre instance.

Flux de travail typique :

1. Demandez à OpenClaw d'éteindre toutes les lumières du salon et de régler le thermostat à 20°C.
2. L'agent appelle l'API Home Assistant, identifie les entités concernées et exécute les appels de service.
3. La confirmation est renvoyée instantanément — pas besoin d'ouvrir l'application ou le tableau de bord Home Assistant.

Ce skill est idéal pour les développeurs qui utilisent déjà Home Assistant et souhaitent un accès plus rapide et scriptable à leur maison connectée. Il se combine parfaitement avec le skill Slack pour envoyer des notifications domotiques sur vos canaux d'équipe, et s'intègre naturellement avec les déploiements basés sur Docker si vous exécutez Home Assistant dans un conteneur.

Prérequis pour le skill Home Assistant

Avant d'installer le skill Home Assistant, assurez-vous d'avoir :

• OpenClaw installé et en cours d'exécution (v1.0+)
• Une instance Home Assistant (v2023.1+) accessible sur le réseau — guide d'installation
• Un jeton d'accès longue durée généré depuis votre profil Home Assistant
• Un accès réseau depuis votre machine vers l'instance Home Assistant (local ou distant)
• clawhub CLI installé pour la gestion des skills

Vérifiez votre configuration :

# Vérifier la version d'OpenClaw
openclaw --version

# Tester la connectivité API de Home Assistant
curl -s -H "Authorization: Bearer YOUR_TOKEN" \
  http://YOUR_HA_HOST:8123/api/ | head -1

# Vérifier clawhub CLI
clawhub --version

Si l'API retourne {"message": "API running."}, votre instance Home Assistant est prête.

Comment installer le skill Home Assistant

Installez le skill Home Assistant avec une seule commande :

npx clawhub@latest install home-assistant

Pour vérifier l'installation :

clawhub list

Vous devriez voir home-assistant dans la liste des skills installés. Installez avec clawhub CLI pour l'expérience de configuration la plus rapide.

Configuration du skill Home Assistant

Le skill nécessite une URL Home Assistant et un jeton d'accès longue durée pour authentifier les requêtes API.

Générer un jeton d'accès longue durée

1. Ouvrez votre tableau de bord Home Assistant à l'adresse http://YOUR_HA_HOST:8123.
2. Cliquez sur l'icône de votre profil (coin inférieur gauche).
3. Faites défiler jusqu'à Jetons d'accès longue durée et cliquez sur Créer un jeton.
4. Nommez-le openclaw-agent et copiez le jeton généré.

Configuration de l'environnement

Définissez les variables d'environnement suivantes :

# URL de l'instance Home Assistant (inclure le port si non standard)
export HOMEASSISTANT_URL="http://192.168.1.100:8123"

# Jeton d'accès longue durée
export HOMEASSISTANT_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6..."

Vous pouvez les ajouter à votre profil shell (~/.bashrc, ~/.zshrc) ou utiliser un fichier .env avec un gestionnaire de secrets.

Important : Ne codez jamais les jetons en dur dans les fichiers de configuration et ne les commitez pas dans le contrôle de version. Utilisez des variables d'environnement ou un gestionnaire de secrets dédié comme 1Password.

Optionnel : Accès distant

Si votre instance Home Assistant n'est pas sur le même réseau, configurez l'accès distant via :

| Méthode | Description | |---------|-------------| | Nabu Casa | Home Assistant Cloud — option la plus simple, fournit une URL distante | | Proxy inverse | Nginx ou Caddy avec terminaison SSL | | Tailscale/WireGuard | Tunnel VPN pour un accès sécurisé de type LAN |

Exemples d'utilisation du skill Home Assistant

1. Contrôler les lumières et les appareils

Vous : « Éteins toutes les lumières dans la chambre et règle la luminosité du salon à 40%. »

L'agent appelle light.turn_off pour les entités de la chambre et light.turn_on avec brightness_pct: 40 pour les lumières du salon. Il identifie les entités par attribution de pièce et renvoie un résumé de confirmation.

2. Interroger les données des capteurs

Vous : « Quelle est la température actuelle dans le bureau et la consommation totale d'énergie aujourd'hui ? »

L'agent interroge les entités sensor.office_temperature et sensor.energy_daily, renvoyant des relevés formatés : « Température du bureau : 22,3°C. Consommation d'énergie du jour : 14,7 kWh. » Il gère les conversions d'unités et formate les données pour une meilleure lisibilité.

3. Créer une automatisation

Vous : « Crée une automatisation qui allume la lumière du porche au coucher du soleil et l'éteint à 23h chaque soir. »

L'agent construit une automatisation Home Assistant en utilisant le déclencheur sun pour le coucher du soleil et un déclencheur time pour 23:00. Il enregistre l'automatisation via l'API, lui attribue un nom descriptif et confirme qu'elle est activée.

4. Activer des scènes

Vous : « Active la scène soirée cinéma. »

L'agent appelle scene.turn_on pour scene.movie_night, ce qui tamise les lumières, ferme les stores et règle le lecteur multimédia sur la bonne entrée — le tout configuré dans votre définition de scène existante.

5. Diagnostiquer l'état des appareils

Vous : « Quels appareils sont actuellement indisponibles ou hors ligne ? »

L'agent interroge toutes les entités ayant un état unavailable ou unknown, les regroupe par intégration et renvoie un rapport de diagnostic : « 3 appareils hors ligne — Capteur de mouvement Zigbee (vu pour la dernière fois il y a 2h), Prise connectée cuisine (injoignable), Intégration météo (délai d'attente API dépassé). »

Sécurité et bonnes pratiques

Suivez ces recommandations pour garder votre maison connectée sécurisée :

• Utilisez le principe du moindre privilège. Créez un utilisateur Home Assistant dédié à OpenClaw avec des permissions limitées aux pièces et appareils que vous souhaitez que l'agent contrôle. Évitez d'utiliser le jeton de votre compte administrateur.
• Vérifiez avant de confirmer. L'agent décrit ce qu'il prévoit de faire avant d'exécuter des actions destructives comme la suppression d'automatisations ou la désactivation d'intégrations. Vérifiez toujours le résumé des actions.
• Sécurisez votre jeton. Les jetons d'accès longue durée fournissent un accès complet à l'API. Stockez-les dans des variables d'environnement, jamais dans des fichiers texte. Renouvelez périodiquement les jetons depuis votre profil Home Assistant.
• Utilisez HTTPS. Si vous accédez à Home Assistant à distance, utilisez toujours HTTPS avec un certificat SSL valide. N'exposez jamais votre instance sur Internet public sans chiffrement.
• Restreignez l'accès réseau. Limitez l'accès API aux plages d'IP de confiance en utilisant les ip_bans de Home Assistant ou des règles de pare-feu. Consultez la checklist de sécurité pour les recommandations générales de sécurité OpenClaw.

Résolution des erreurs courantes

« 401 Unauthorized — Invalid access token »

Le jeton d'accès longue durée est invalide ou expiré.

1. Vérifiez que le jeton est correctement défini :

echo $HOMEASSISTANT_TOKEN

2. Générez un nouveau jeton depuis la page de profil de votre Home Assistant.
3. Assurez-vous qu'il n'y a pas d'espaces ou de sauts de ligne supplémentaires dans la valeur du jeton.

« Connection refused — Cannot reach Home Assistant »

L'agent ne peut pas se connecter à votre instance Home Assistant.

1. Vérifiez que l'URL est correcte et inclut le port :

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

2. Vérifiez que Home Assistant est en cours d'exécution : sudo systemctl status homeassistant (pour les installations supervisées).
3. Si vous utilisez Docker, confirmez que le conteneur est en cours d'exécution : docker ps | grep homeassistant.
4. Vérifiez les règles de pare-feu — le port 8123 doit être accessible depuis votre machine.

« Entity not found — light.living_room »

L'identifiant de l'entité ne correspond à aucun appareil dans Home Assistant.

1. Listez toutes les entités disponibles :

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

2. Les identifiants d'entités sont sensibles à la casse et utilisent des underscores — vérifiez les fautes de frappe.
3. Si l'appareil a été ajouté récemment, redémarrez Home Assistant pour actualiser l'enregistrement des entités.