Habilidade Home Assistant para OpenClaw

Visão Geral do Skill Home Assistant do OpenClaw

O skill Home Assistant conecta o OpenClaw à sua instância do Home Assistant, transformando seu agente de IA em um poderoso controlador de casa inteligente. Em vez de navegar por painéis ou editar arquivos de configuração YAML, você pode gerenciar toda a sua casa inteligente através de linguagem natural — alternar luzes, verificar leituras de sensores, criar automações e solucionar problemas de dispositivos, tudo a partir do seu terminal.

O Home Assistant é a maior plataforma de automação residencial de código aberto do mundo, com suporte a mais de 2.000 integrações com dispositivos de Philips Hue, Zigbee, Z-Wave, Matter e centenas de outros. O skill Home Assistant do OpenClaw utiliza a API REST do Home Assistant para dar ao seu agente acesso direto a entidades, serviços, automações e scripts em execução na sua instância.

Fluxo de trabalho típico:

1. Peça ao OpenClaw para apagar todas as luzes da sala de estar e ajustar o termostato para 20°C.
2. O agente chama a API do Home Assistant, identifica as entidades relevantes e executa as chamadas de serviço.
3. A confirmação é retornada instantaneamente — sem necessidade de abrir o aplicativo ou o painel do Home Assistant.

Este skill é ideal para desenvolvedores que já utilizam o Home Assistant e desejam acesso mais rápido e programável à sua casa inteligente. Ele funciona bem com o skill Slack para enviar notificações de casa inteligente para os canais da sua equipe, e se integra naturalmente com implantações baseadas em Docker se você executa o Home Assistant em um contêiner.

Pré-requisitos para o Skill Home Assistant

Antes de instalar o skill Home Assistant, certifique-se de que você tem:

• OpenClaw instalado e em execução (v1.0+)
• Uma instância do Home Assistant (v2023.1+) acessível pela rede — guia de instalação
• Um Token de Acesso de Longa Duração gerado a partir do seu perfil do Home Assistant
• Acesso à rede da sua máquina à instância do Home Assistant (local ou remoto)
• CLI clawhub instalado para gerenciamento de skills

Verifique sua configuração:

# Verificar a versão do OpenClaw
openclaw --version

# Testar conectividade com a API do Home Assistant
curl -s -H "Authorization: Bearer YOUR_TOKEN" \
  http://YOUR_HA_HOST:8123/api/ | head -1

# Verificar o CLI clawhub
clawhub --version

Se a API retornar {"message": "API running."}, sua instância do Home Assistant está pronta.

Como Instalar o Skill Home Assistant

Instale o skill Home Assistant com um único comando:

npx clawhub@latest install home-assistant

Para verificar a instalação:

clawhub list

Você deve ver home-assistant na lista de skills instalados. Instale com o CLI clawhub para a experiência de configuração mais rápida.

Configuração do Skill Home Assistant

O skill requer uma URL do Home Assistant e um token de acesso de longa duração para autenticar as requisições à API.

Gerar um Token de Acesso de Longa Duração

1. Abra o painel do Home Assistant em http://YOUR_HA_HOST:8123.
2. Clique no ícone do seu perfil (canto inferior esquerdo).
3. Role até Tokens de Acesso de Longa Duração e clique em Criar Token.
4. Nomeie como openclaw-agent e copie o token gerado.

Configuração de Ambiente

Defina as seguintes variáveis de ambiente:

# URL da instância do Home Assistant (inclua a porta se não for padrão)
export HOMEASSISTANT_URL="http://192.168.1.100:8123"

# Token de acesso de longa duração
export HOMEASSISTANT_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6..."

Você pode adicioná-las ao perfil do seu shell (~/.bashrc, ~/.zshrc) ou usar um arquivo .env com um gerenciador de segredos.

Importante: Nunca insira tokens diretamente em arquivos de configuração ou os envie para o controle de versão. Use variáveis de ambiente ou um gerenciador de segredos dedicado como o 1Password.

Opcional: Acesso Remoto

Se sua instância do Home Assistant não está na mesma rede, configure o acesso remoto via:

| Método | Descrição | |--------|-----------| | Nabu Casa | Home Assistant Cloud — opção mais fácil, fornece uma URL remota | | Proxy reverso | Nginx ou Caddy com terminação SSL | | Tailscale/WireGuard | Túnel VPN para acesso seguro semelhante à rede local |

Exemplos de Uso do Skill Home Assistant

1. Controlar Luzes e Dispositivos

Você: "Apague todas as luzes do quarto e ajuste o brilho da sala de estar para 40%."

O agente chama light.turn_off para as entidades do quarto e light.turn_on com brightness_pct: 40 para as luzes da sala de estar. Ele identifica as entidades pela atribuição de cômodo e retorna um resumo de confirmação.

2. Consultar Dados de Sensores

Você: "Qual é a temperatura atual do escritório e o consumo total de energia hoje?"

O agente consulta as entidades sensor.office_temperature e sensor.energy_daily, retornando leituras formatadas: "Temperatura do escritório: 22,3°C. Consumo de energia hoje: 14,7 kWh." Ele lida com conversões de unidade e formata os dados para facilitar a leitura.

3. Criar uma Automação

Você: "Crie uma automação que acenda a luz da varanda ao pôr do sol e a apague às 23h todas as noites."

O agente cria uma automação no Home Assistant usando o gatilho sun para o pôr do sol e um gatilho time para as 23:00. Ele registra a automação via API, atribui um nome descritivo e confirma que ela está habilitada.

4. Ativar Cenas

Você: "Ative a cena noite de cinema."

O agente chama scene.turn_on para scene.movie_night, que escurece as luzes, fecha as persianas e configura o media player para a entrada correta — tudo configurado na sua definição de cena existente.

5. Solucionar Problemas de Status dos Dispositivos

Você: "Quais dispositivos estão indisponíveis ou offline no momento?"

O agente consulta todas as entidades com estado unavailable ou unknown, agrupa por integração e retorna um relatório de diagnóstico: "3 dispositivos offline — Sensor de movimento Zigbee (última vez visto há 2h), Tomada inteligente cozinha (inacessível), Integração de clima (tempo de resposta da API excedido)."

Segurança e Boas Práticas

Siga estas diretrizes para manter sua casa inteligente segura:

• Use o princípio do menor privilégio. Crie um usuário dedicado no Home Assistant para o OpenClaw com permissões limitadas aos cômodos e dispositivos que você deseja que o agente controle. Evite usar o token da sua conta de administrador.
• Revise antes de confirmar. O agente descreverá o que planeja fazer antes de executar ações destrutivas, como excluir automações ou desabilitar integrações. Sempre revise o resumo da ação.
• Proteja seu token. Tokens de acesso de longa duração fornecem acesso completo à API. Armazene-os em variáveis de ambiente, nunca em arquivos de texto simples. Rotacione os tokens periodicamente a partir do seu perfil do Home Assistant.
• Use HTTPS. Se acessar o Home Assistant remotamente, sempre use HTTPS com um certificado SSL válido. Nunca exponha sua instância na internet pública sem criptografia.
• Restrinja o acesso à rede. Limite o acesso à API a faixas de IP confiáveis usando ip_bans do Home Assistant ou regras de firewall. Consulte a Lista de Verificação de Segurança para orientações gerais de segurança do OpenClaw.

Solução de Erros Comuns

"401 Unauthorized — Token de acesso inválido"

O token de acesso de longa duração é inválido ou expirou.

1. Verifique se o token está configurado corretamente:

echo $HOMEASSISTANT_TOKEN

2. Gere um novo token na página de perfil do Home Assistant.
3. Certifique-se de que não há espaços em branco ou quebras de linha extras no valor do token.

"Connection refused — Não é possível acessar o Home Assistant"

O agente não consegue se conectar à sua instância do Home Assistant.

1. Verifique se a URL está correta e inclui a porta:

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

2. Verifique se o Home Assistant está em execução: sudo systemctl status homeassistant (para instalações supervisionadas).
3. Se estiver usando Docker, confirme se o contêiner está em execução: docker ps | grep homeassistant.
4. Verifique as regras de firewall — a porta 8123 deve estar acessível a partir da sua máquina.

"Entity not found — light.living_room"

O ID da entidade não corresponde a nenhum dispositivo no Home Assistant.

1. Liste todas as entidades disponíveis:

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

2. Os IDs de entidade diferenciam maiúsculas de minúsculas e usam sublinhados — verifique se há erros de digitação.
3. Se o dispositivo foi adicionado recentemente, reinicie o Home Assistant para atualizar o registro de entidades.