Habilidad Home Assistant para OpenClaw

Descripción general del skill de Home Assistant para OpenClaw

El skill de Home Assistant conecta OpenClaw a tu instancia de Home Assistant, convirtiendo tu agente de IA en un potente controlador de hogar inteligente. En lugar de navegar por paneles de control o editar archivos de configuración YAML, puedes gestionar todo tu hogar inteligente mediante lenguaje natural — encender y apagar luces, consultar lecturas de sensores, crear automatizaciones y diagnosticar problemas con dispositivos, todo desde tu terminal.

Home Assistant es la plataforma de automatización del hogar de código abierto más grande del mundo, compatible con más de 2000 integraciones con dispositivos de Philips Hue, Zigbee, Z-Wave, Matter y cientos más. El skill de Home Assistant para OpenClaw aprovecha la API REST de Home Assistant para dar a tu agente acceso directo a entidades, servicios, automatizaciones y scripts que se ejecutan en tu instancia.

Flujo de trabajo típico:

1. Pide a OpenClaw que apague todas las luces del salón y configure el termostato a 20°C.
2. El agente llama a la API de Home Assistant, identifica las entidades relevantes y ejecuta las llamadas de servicio.
3. La confirmación se devuelve al instante — sin necesidad de abrir la aplicación o el panel de Home Assistant.

Este skill es ideal para desarrolladores que ya ejecutan Home Assistant y desean un acceso más rápido y programable a su hogar inteligente. Se combina bien con el skill de Slack para enviar notificaciones del hogar inteligente a los canales de tu equipo, y se integra naturalmente con despliegues basados en Docker si ejecutas Home Assistant en un contenedor.

Requisitos previos para el skill de Home Assistant

Antes de instalar el skill de Home Assistant, asegúrate de tener:

• OpenClaw instalado y en ejecución (v1.0+)
• Una instancia de Home Assistant (v2023.1+) accesible a través de la red — guía de instalación
• Un Token de Acceso de Larga Duración generado desde tu perfil de Home Assistant
• Acceso de red desde tu máquina a la instancia de Home Assistant (local o remoto)
• clawhub CLI instalado para la gestión de skills

Verifica tu configuración:

# Verificar la versión de OpenClaw
openclaw --version

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

# Verificar clawhub CLI
clawhub --version

Si la API devuelve {"message": "API running."}, tu instancia de Home Assistant está lista.

Cómo instalar el skill de Home Assistant

Instala el skill de Home Assistant con un solo comando:

npx clawhub@latest install home-assistant

Para verificar la instalación:

clawhub list

Deberías ver home-assistant en la lista de skills instalados. Instala con clawhub CLI para la experiencia de configuración más rápida.

Configuración del skill de Home Assistant

El skill requiere una URL de Home Assistant y un token de acceso de larga duración para autenticar las solicitudes a la API.

Generar un Token de Acceso de Larga Duración

1. Abre tu panel de Home Assistant en http://YOUR_HA_HOST:8123.
2. Haz clic en el icono de tu perfil (esquina inferior izquierda).
3. Desplázate hasta Long-Lived Access Tokens y haz clic en Create Token.
4. Nómbralo openclaw-agent y copia el token generado.

Configuración del entorno

Establece las siguientes variables de entorno:

# URL de la instancia de Home Assistant (incluye el puerto si no es estándar)
export HOMEASSISTANT_URL="http://192.168.1.100:8123"

# Token de acceso de larga duración
export HOMEASSISTANT_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6..."

Puedes añadirlas a tu perfil de shell (~/.bashrc, ~/.zshrc) o usar un archivo .env con un gestor de secretos.

Importante: Nunca escribas tokens directamente en archivos de configuración ni los incluyas en el control de versiones. Usa variables de entorno o un gestor de secretos dedicado como 1Password.

Opcional: Acceso remoto

Si tu instancia de Home Assistant no está en la misma red, configura el acceso remoto mediante:

| Método | Descripción | |--------|-------------| | Nabu Casa | Home Assistant Cloud — la opción más fácil, proporciona una URL remota | | Proxy inverso | Nginx o Caddy con terminación SSL | | Tailscale/WireGuard | Túnel VPN para acceso seguro tipo LAN |

Ejemplos de uso del skill de Home Assistant

1. Controlar luces y dispositivos

Tú: "Apaga todas las luces del dormitorio y ajusta el brillo del salón al 40%."

El agente llama a light.turn_off para las entidades del dormitorio y a light.turn_on con brightness_pct: 40 para las luces del salón. Identifica las entidades por asignación de habitación y devuelve un resumen de confirmación.

2. Consultar datos de sensores

Tú: "¿Cuál es la temperatura actual de la oficina y el consumo total de energía de hoy?"

El agente consulta las entidades sensor.office_temperature y sensor.energy_daily, devolviendo lecturas formateadas: "Temperatura de la oficina: 22.3°C. Consumo de energía de hoy: 14.7 kWh." Gestiona conversiones de unidades y formatea los datos para su legibilidad.

3. Crear una automatización

Tú: "Crea una automatización que encienda la luz del porche al atardecer y la apague a las 11 PM todas las noches."

El agente construye una automatización de Home Assistant usando el disparador sun para el atardecer y un disparador time para las 23:00. Registra la automatización a través de la API, asigna un nombre descriptivo y confirma que está habilitada.

4. Activar escenas

Tú: "Activa la escena de noche de cine."

El agente llama a scene.turn_on para scene.movie_night, que atenúa las luces, cierra las persianas y configura el reproductor multimedia en la entrada correcta — todo según la definición de escena existente.

5. Diagnosticar el estado de dispositivos

Tú: "¿Qué dispositivos están actualmente no disponibles o desconectados?"

El agente consulta todas las entidades con estado unavailable o unknown, las agrupa por integración y devuelve un informe diagnóstico: "3 dispositivos desconectados — Sensor de movimiento Zigbee (última conexión hace 2h), Enchufe inteligente cocina (inalcanzable), Integración meteorológica (tiempo de espera de API agotado)."

Seguridad y buenas prácticas

Sigue estas directrices para mantener tu hogar inteligente seguro:

• Usa el mínimo privilegio. Crea un usuario de Home Assistant dedicado para OpenClaw con permisos limitados a las habitaciones y dispositivos que deseas que el agente controle. Evita usar el token de tu cuenta de administrador.
• Revisa antes de confirmar. El agente describirá lo que planea hacer antes de ejecutar acciones destructivas como eliminar automatizaciones o deshabilitar integraciones. Siempre revisa el resumen de la acción.
• Protege tu token. Los tokens de acceso de larga duración proporcionan acceso completo a la API. Almacénalos en variables de entorno, nunca en archivos de texto plano. Rota los tokens periódicamente desde tu perfil de Home Assistant.
• Usa HTTPS. Si accedes a Home Assistant de forma remota, utiliza siempre HTTPS con un certificado SSL válido. Nunca expongas tu instancia en internet público sin cifrado.
• Restringe el acceso de red. Limita el acceso a la API a rangos de IP de confianza usando ip_bans de Home Assistant o reglas de firewall. Revisa la Lista de verificación de seguridad para orientación general sobre seguridad en OpenClaw.

Solución de errores comunes

"401 Unauthorized — Invalid access token"

El token de acceso de larga duración es inválido o ha expirado.

1. Verifica que el token esté configurado correctamente:

echo $HOMEASSISTANT_TOKEN

2. Genera un nuevo token desde la página de perfil de Home Assistant.
3. Asegúrate de que no haya espacios en blanco adicionales ni saltos de línea en el valor del token.

"Connection refused — Cannot reach Home Assistant"

El agente no puede conectarse a tu instancia de Home Assistant.

1. Verifica que la URL sea correcta e incluya el puerto:

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

2. Comprueba que Home Assistant esté en ejecución: sudo systemctl status homeassistant (para instalaciones supervisadas).
3. Si usas Docker, confirma que el contenedor esté ejecutándose: docker ps | grep homeassistant.
4. Revisa las reglas del firewall — el puerto 8123 debe ser accesible desde tu máquina.

"Entity not found — light.living_room"

El ID de entidad no coincide con ningún dispositivo en Home Assistant.

1. Lista todas las entidades disponibles:

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

2. Los IDs de entidad distinguen entre mayúsculas y minúsculas y usan guiones bajos — verifica si hay errores tipográficos.
3. Si el dispositivo fue añadido recientemente, reinicia Home Assistant para actualizar el registro de entidades.