Tutorial · Casa inteligente e IA
Home Assistant com IA: luzes e ar no mesmo painel
Monte a central, faça a primeira luz responder, traga o Gree e abra os dois controles no celular. No fim, use a lâmpada para avisar quando o Claude Code pedir permissão.

SumárioComeço
- O que você vai montar
- Baixe os arquivos e escolha onde trabalhar
- Prepare o Home Assistant no Linux
- Inicie e confira se os dados permanecem
- Faça a primeira luz responder
- Encontre e integre o ar-condicionado
- Monte o painel e abra no celular
- Peça uma interface do seu jeito
- Prepare o pulso azul e a restauração
- Ligue o aviso ao pedido do Claude Code
- Confira o teste e resolva as falhas
- Guarde a base e escolha o próximo passo
01
O que você vai montar
Uma luz, um ar-condicionado e uma tela no celular para controlar os dois. Neste guia, você monta a base que mostro no vídeo: Home Assistant em um computador de casa, integração com os aparelhos e um painel nativo. No final, uma luz RGB fica azul por cinco segundos quando o Claude Code pede permissão.
No meu estúdio, o servidor é um ZimaCube. Você pode aproveitar outro computador compatível. O Home Assistant recebe o toque no painel e conversa com o aparelho. O Claude Code ajuda a preparar arquivos e descobrir o caminho da configuração. Depois de pronto, o painel funciona sem fazer uma consulta à IA a cada toque.
Separe antes de começar
- Um computador Linux na rede de casa, com Docker Engine e Docker Compose disponíveis. Ele precisa ficar ligado para atender o painel.
- Um celular na mesma rede. O servidor pode usar cabo e o celular, Wi-Fi do mesmo roteador.
- Uma lâmpada compatível com uma integração do Home Assistant. Para repetir o exemplo Tuya, ela já deve funcionar no Smart Life ou Tuya Smart.
- Opcional: um ar Gree compatível já conectado ao Wi-Fi pelo aplicativo do fabricante. Dá para montar o primeiro painel só com a luz.
- Claude Code instalado e autenticado no computador em que você vai conversar com o agente. O aviso azul exige uma lâmpada RGB e uma sessão interativa no terminal.
O Home Assistant e os arquivos deste guia são gratuitos. Entram na conta o hardware que você já tem, energia e o uso do Claude Code conforme seu plano. A integração Tuya deste percurso usa o serviço da Tuya na internet.
02
Baixe os arquivos e escolha onde trabalhar
Baixar todos os materiais (.zip)
O pacote tem o Compose, os dois cartões, a automação da luz azul, o script do aviso, a configuração do hook e os prompts. São exemplos com campos para substituir pelos da sua casa.
- compose.yaml: fica no servidor Linux.
- cartoes.yaml: exemplos para o editor de cartões.
- automacao-luz-azul.yaml: entra no editor de uma automação nova.
- alerta-local.sh e settings.local.json: ficam no computador com Claude Code.
- Todos os prompts e instruções do pacote.
Dois computadores, dois terminais
No vídeo, converso com o Claude Code no Mac e o Home Assistant roda no Linux do ZimaCube. O acesso por SSH abre o terminal do servidor a partir do Mac. Os comandos Docker deste guia rodam no Linux do servidor. Se você usa um único computador Linux, pode fazer tudo nele.
Instale o Claude Code pelo guia oficial. Os comandos do aviso usam um terminal macOS ou Linux; no Windows, use um ambiente Linux como o WSL. Para conversar no Mac e executar no servidor, configure o SSH, conclua a autenticação no terminal e confira a identidade do destino.
ssh USUARIO_DO_SERVIDOR@ENDERECO_DO_SERVIDOR
uname -nsmO segundo comando deve mostrar o nome e o sistema da máquina onde você entrou. Não envie sua senha ao chat. No Claude Code, abra uma pasta de trabalho separada e comece com este pedido:
Estou usando Claude Code no Mac. O Home Assistant desta demonstração
vai rodar em outro computador Linux da minha rede de casa. Confira
comigo o host de teste e o acesso SSH já configurado neste Mac.
Mostre o nome e o sistema do destino antes de criar qualquer arquivo.
Use uma pasta nova ~/home-assistant-demo no servidor e confira se a porta
8123 está livre. Quero preparar o Compose no servidor. Deixe os serviços
que já existem preservados. Os comandos Docker serão executados no Linux.03
Prepare o Home Assistant no Linux
Instale o Docker Engine para sua distribuição e, se necessário, o plugin Compose. No terminal do servidor, confira:
docker --version
docker compose version
docker infoOs três comandos precisam funcionar. O último confirma que o usuário consegue acessar o serviço do Docker. Se aparecer erro de permissão ou comando não encontrado, resolva a instalação antes de continuar.
Crie uma pasta nova para este projeto. O Compose usa um arquivo YAML para dizer qual programa iniciar, como ele acessa a rede e onde os dados ficam guardados.
mkdir -p ~/home-assistant-demo
cd ~/home-assistant-demo
pwdNa pasta home-assistant-demo do host Linux confirmado, prepare um
compose.yaml para um Home Assistant Container de teste.
Use a imagem ghcr.io/home-assistant/home-assistant:2026.10.4, rede do host
e uma pasta ./config montada em /config. Use meu fuso America/Fortaleza.
Esta demonstração usa Tuya oficial e Gree no Wi-Fi. Comece sem modo
privilegiado, acesso USB ou D-Bus. Mostre os arquivos, explique onde ficam
os dados e dê os comandos de validação e recriação. Deixe a decisão de
subir o serviço comigo.Confira o arquivo gerado com esta referência, ou salve o compose.yaml baixado na pasta:
services:
homeassistant:
image: ghcr.io/home-assistant/home-assistant:2026.10.4
network_mode: host
restart: unless-stopped
stop_grace_period: 60s
environment:
TZ: America/Fortaleza
volumes:
- ./config:/configimage aponta para a imagem oficial, fixada na versão de referência do vídeo. ./config:/config guarda a configuração na pasta do projeto. network_mode: host usa a rede do Linux, inclusive para a descoberta local do Gree. Ajuste TZ se seu fuso for outro.
Este recorte usa aparelhos de rede, sem USB, Bluetooth, D-Bus ou modo privilegiado. Outros dispositivos têm requisitos próprios. Compare com a documentação de instalação em Linux antes de ampliar a configuração. O caminho com rede do host foi escrito para Linux.
04
Inicie e confira se os dados permanecem
Na pasta do Compose, valide o arquivo antes de iniciar o serviço:
cd ~/home-assistant-demo
mkdir -p config
docker compose config --quiet
docker compose up -d
docker compose ps
docker compose logs --tail=30 homeassistantA validação sem mensagens indica que o Compose conseguiu ler a configuração. A primeira inicialização pode levar alguns minutos; acompanhe o estado e os logs. No navegador, abra http://ENDERECO_DO_HOST:8123, substituindo o endereço pelo do Linux. No celular, use esse mesmo endereço na rede de casa. localhost no celular apontaria para o próprio celular.
Crie sua conta na primeira abertura. Em Configurações → Áreas, rótulos e zonas, crie a área Estúdio, ou o nome do seu cômodo. Os rótulos podem variar com a versão.
Agora, apenas nesta instalação de teste, recrie o container e abra a página novamente:
cd ~/home-assistant-demo
docker compose up -d --force-recreate homeassistant
docker compose ps- A página abre novamente com a mesma conta.
- A área criada continua aparecendo.
- A pasta config permanece no servidor, mesmo depois da recriação.
O container pode ser substituído; a pasta de dados continua montada. Isso confirma a persistência desta instalação, mas não substitui um backup. Antes de atualizações futuras, guarde uma cópia recuperável da configuração e confira as notas da versão.
05
Faça a primeira luz responder
No meu exemplo, a lâmpada Topo já funcionava no Smart Life. Se a sua for compatível, faça o pareamento no app e teste ligar e desligar por lá primeiro. Para outra marca, procure a integração correspondente ao modelo.
- No Home Assistant, abra Configurações → Dispositivos e serviços → Adicionar integração e procure Tuya.
- No Smart Life ou Tuya Smart, abra Eu → Configurações → Conta e segurança e localize o código de usuário.
- Informe o código na configuração e escaneie o QR pelo aplicativo. Faça o vínculo com o QR em outra tela.
- Abra a lâmpada importada, dê um nome reconhecível e atribua a área Estúdio.
Uma integração faz a ponte com o aparelho ou serviço. Uma entidade é o item do Home Assistant que representa um estado e seus controles. Para os próximos exemplos, anote o ID da entidade da sua luz, algo como light.luz_de_teste. O nome amigável e o ID podem ser diferentes.
Estou no Home Assistant 2026.10.4 e minha lâmpada já aparece no Smart Life.
Explique como conferir se a integração oficial Tuya trouxe essa lâmpada e
como distinguir uma luz com cor de uma luz que só aceita brilho. Use
somente o nome de demonstração e os modos que eu colar. Se faltar uma
informação, diga em qual tela eu devo conferir.Teste na tela da própria entidade: ligar, baixar o brilho e mudar a cor, se houver suporte. Confira a lâmpada física. Uma luz que só regula brilho não ganha RGB por entrar no painel.
- Ligar e desligar na entidade faz a lâmpada reagir.
- O brilho e a cor disponíveis correspondem ao que o aparelho oferece.
- O estado da entidade acompanha a resposta física.
A Tuya oficial usa o serviço da Tuya. Se faltar um aparelho ou uma função, confira os limites documentados e recarregue a integração depois de adicionar novos dispositivos no app. Guarde códigos de conta e QR de vínculo fora de capturas e mensagens públicas.
06
Encontre e integre o ar-condicionado
Meu Gree já estava no Wi-Fi pelo aplicativo do fabricante. Foi aí que pedi ao Claude para procurar o aparelho na rede. Ele precisa de uma ferramenta com acesso a essa rede, como o terminal local ou a conexão SSH ao Linux que preparamos. Uma conversa na nuvem, sozinha, não tem esse acesso.
Procure meu ar-condicionado Gree na rede de casa e me ajude a integrá-lo
ao Home Assistant 2026.10.4. Ele já está pareado no app do fabricante.
Use o terminal local ou o acesso SSH configurado ao host Linux da mesma
LAN. Confirme a rede de destino comigo e consulte a documentação e o
fluxo de descoberta da integração Gree antes de escolher a consulta.
Faça a identificação em somente leitura, com descoberta dirigida ao Gree.
Mostre a consulta usada e a evidência de qual aparelho foi encontrado.
Ajude a concluir a adição em Dispositivos e serviços na sessão do HA que
eu abrir. Eu faço o login e os passos de confirmação na interface.
Depois confira comigo modo, temperatura ambiente e alvo. Aguarde minha
confirmação para testar um novo alvo e então restaure o ajuste anterior.A busca precisa produzir uma evidência: qual consulta foi feita, qual aparelho respondeu e como isso combina com seu modelo ou com o app. Um IP ou um nome parecido com a marca serve de pista. Confira a identificação antes de testar comandos.
- Confirme que o ar já está associado ao Wi-Fi no app do fabricante. A integração não faz esse pareamento inicial.
- No Home Assistant, adicione Gree Climate em Dispositivos e serviços e siga a descoberta.
- Se não aparecer, confira a rede do servidor e do ar e o isolamento do Wi-Fi. Use a lista de aparelhos do roteador como apoio para identificar o seu.
- Abra o dispositivo encontrado, dê um nome e atribua a área. Confira o ID, como
climate.ar_de_teste.
Separe as duas leituras: temperatura ambiente é o que o aparelho está medindo; alvo é o valor que você pediu. Anote o ajuste inicial, mude o alvo e confirme que o pedido chegou ao aparelho ou app. Depois, restaure o valor anterior. O cômodo leva tempo para esfriar.
Confira o modelo na documentação da Gree Climate. Se não houver compatibilidade, mantenha a luz no painel e procure a integração do seu aparelho. A descoberta não garante suporte.
07
Monte o painel e abra no celular
Em Configurações → Painéis, crie um painel para o Estúdio. Abra-o, entre no modo de edição e adicione um cartão Luz para sua lâmpada e um Termostato para o ar.
Quero um painel nativo simples de Home Assistant para o celular. Vou
colar o ID de uma entidade de luz e de uma entidade de climatização de
teste e as funções que elas oferecem. Indique os cartões padrão e
diga como conferir o estado da luz, a temperatura do ambiente e a
temperatura-alvo. Mostre também o YAML de cada cartão para comparar com
o que eu monto no editor visual. Se uma entidade estiver indisponível,
a tela precisa deixar isso visível.Se quiser comparar o YAML com o editor visual, use os exemplos abaixo. Troque cada ID pelo da sua instalação. Cole um bloco por cartão no editor de código do cartão.
type: light
entity: light.luz_de_teste
name: Luz de testetype: thermostat
entity: climate.ar_de_teste
name: Ar de testeSalve e abra o painel no navegador do celular, no Wi-Fi de casa. O cartão da luz traz brilho; a cor pode ficar na tela de detalhes. No termostato, confira ambiente e alvo separadamente. Para uma entidade indisponível, o painel precisa mostrar que ela está sem resposta.
- O painel abre no celular pelo endereço do servidor.
- Brilho e cor da luz foram conferidos no aparelho.
- Um novo alvo chega ao ar, e o ajuste anterior foi restaurado.
- Os nomes permitem reconhecer qual aparelho cada cartão controla.
Se os dois cartões resolvem seu uso, a base está pronta. As referências são os painéis do Home Assistant e os cartões Luz e Termostato.
08
Peça uma interface do seu jeito
No vídeo, também mostro a interface personalizada do meu estúdio. Ela veio depois da base: agrupar luzes, enxergar quais estão ligadas e abrir o controle certo sem procurar numa lista grande. Os dois cartões acima são suficientes para seguir o restante do guia.
Para começar uma personalização, descreva o comportamento desejado e forneça apenas os IDs e as funções dos aparelhos que você conferiu. Faça a primeira versão em uma cópia, com dados simulados:
Quero planejar uma interface para o celular a partir do meu painel de Home Assistant.
Agrupe os controles por cômodo. Mostre quais luzes estão ligadas e faça o ícone acompanhar a cor que cada uma reporta. Respeite as luzes que só aceitam brilho.
No ar, separe temperatura ambiente e alvo. Mostre indisponibilidade de forma explícita.
Comece com uma cópia de teste usando dados simulados. Não altere meu painel em uso nem os aparelhos. Teste o arraste do termostato sem mudar a escala durante o gesto.
Explique o que cabe nos cartões nativos e o que exigiria uma interface própria. Não coloque tokens do Home Assistant no código público do navegador.Confira toque, rolagem, arraste e estados sem resposta na cópia. Só depois conecte os controles reais, um por vez. Uma simulação aprovada prova o comportamento da tela; a resposta do aparelho pede outra conferência.
09
Prepare o pulso azul e a restauração
Agora a luz ganha uma segunda função: avisar que o Claude chamou. A automação começa quando recebe um POST em um webhook, um endereço da rede local. Ela guarda o estado da luz, deixa azul por cinco segundos e tenta restaurar o estado anterior.
Use uma lâmpada RGB que você possa testar. Anote se ela está apagada ou acesa, a cor e o brilho. Gere um ID privado no seu terminal:
openssl rand -hex 24Em Configurações → Automações e cenas, crie uma automação vazia. No menu do editor, escolha Editar em YAML. Cole o exemplo, troque light.luz_de_teste nos três lugares e substitua SUBSTITUA_POR_ID_PRIVADO pelo valor gerado. Salve a automação e mantenha-a ativada.
alias: Demo - Claude pediu permissao
description: Pulso azul em uma luz de teste e restauração da cena anterior.
triggers:
- trigger: webhook
webhook_id: SUBSTITUA_POR_ID_PRIVADO
allowed_methods:
- POST
local_only: true
conditions:
- condition: template
value_template: "{{ states('light.luz_de_teste') in ['on', 'off'] }}"
actions:
- action: scene.create
data:
scene_id: demo_antes_aviso_claude
snapshot_entities:
- light.luz_de_teste
- action: light.turn_on
continue_on_error: true
target:
entity_id: light.luz_de_teste
data:
hs_color: [220, 100]
brightness_pct: 45
- delay: "00:00:05"
- action: scene.turn_on
target:
entity_id: scene.demo_antes_aviso_claude
mode: single
max_exceeded: silentmode: single ignora um segundo aviso durante o pulso. Assim ele não fotografa o azul por cima da cena original. A condição impede a sequência quando a luz está indisponível. continue_on_error permite seguir até a tentativa de restauração mesmo se o comando de azul falhar.
A cena criada é temporária. Se o Home Assistant reiniciar no meio do pulso, ela pode desaparecer. Use os valores anotados para restaurar a lâmpada pelo painel. Veja as referências de webhooks, cenas e modos de execução.
10
Ligue o aviso ao pedido do Claude Code
Esta parte fica no computador com Claude Code, que precisa alcançar o Home Assistant na rede. No pacote, abra a pasta claude-aviso. Ela já tem o script e a pasta oculta .claude. Se estiver criando os arquivos à mão, comece em uma pasta de teste nova:
mkdir -p ~/claude-aviso/.claude
cd ~/claude-aviso
pwdSalve este conteúdo como alerta-local.sh, na raiz da pasta:
#!/bin/sh
cat >/dev/null
[ -n "${HA_DEMO_WEBHOOK_URL:-}" ] || exit 0
if ! curl --proto '=http,https' --noproxy '*' --silent --fail --max-time 2 --output /dev/null \
--request POST -- "$HA_DEMO_WEBHOOK_URL"; then
printf '%s\n' 'Aviso local indisponível.' >&2
fi
exit 0O script descarta a entrada do hook, faz apenas o POST e limita a espera a dois segundos. Não imprime uma decisão de aprovação. Salve o JSON abaixo em .claude/settings.local.json na mesma pasta. Se já usa essa pasta para outro projeto, prefira uma nova em vez de sobrescrever suas configurações.
{
"permissions": {
"ask": ["Bash(printf *)"]
},
"hooks": {
"PermissionRequest": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "sh \"$CLAUDE_PROJECT_DIR/alerta-local.sh\""
}
]
}
]
}
}O evento PermissionRequest acompanha um pedido de permissão. Neste teste, o filtro Bash restringe o aviso a essa ferramenta, e a regra ask pede confirmação para o printf do exercício. Reinicie a sessão depois de salvar e confira o registro em /hooks. Referência dos hooks do Claude Code.
Teste o sinal antes de abrir o Claude
Na pasta do script, execute o bloco abaixo no terminal macOS ou Linux. A primeira linha espera você colar a URL completa do webhook e apertar Enter. A entrada fica oculta. O valor não deve ser escrito dentro do comando:
read -rs HA_DEMO_WEBHOOK_URL
printf '\n'
export HA_DEMO_WEBHOOK_URL
sh ./alerta-local.sh </dev/nullA luz deve ficar azul e voltar ao estado inicial. Abra a trilha da automação no Home Assistant e confira a passagem pelas ações. Uma resposta HTTP, sozinha, não comprova que a lâmpada mudou.
Deixe a variável exportada e, no mesmo terminal e na mesma pasta, abra uma sessão interativa:
claude --permission-mode defaultEnvie este pedido e deixe a pergunta de permissão aberta enquanto observa a luz:
Use a ferramenta Bash para executar apenas este comando, sem reformulá-lo:
printf '%s\n' 'teste de aprovação'O aviso deve ocorrer enquanto a decisão continua no terminal. Aguarde a restauração da luz e escolha aprovar ou recusar. Comando já autorizado ou sessão que pula permissões não serve para demonstrar esse pedido.
11
Confira o teste e resolva as falhas
| Teste | O que conferir |
|---|---|
| Luz apagada antes do aviso | Fica azul e apaga ao final. |
| Luz acesa com outra cor | Volta à cor e ao brilho anotados antes do POST. |
| Dois avisos próximos | Apenas o primeiro inicia a sequência; o segundo é ignorado durante os cinco segundos. |
| Luz sem resposta | A trilha mostra a condição impedindo o início da sequência. |
| Pedido de permissão | A luz muda enquanto a decisão continua aberta no terminal. |
Se uma etapa não funcionar
| Sintoma | O que conferir |
|---|---|
| O painel não abre | Endereço do servidor, porta 8123, estado em docker compose ps, logs, firewall e rede de convidados. |
| A configuração sumiu ao recriar | Se você está na mesma pasta do Compose e se ./config aponta para a pasta de dados que usou antes. Não recrie a conta antes de localizar a configuração original. |
| Tuya não mostra um controle | Funcionamento no app, conta vinculada e funções suportadas pela integração oficial. |
| Gree não aparece | Pareamento no app do fabricante, compatibilidade do modelo e descoberta na mesma rede do servidor. |
| O script não acende a luz | URL completa na variável, rede local, ID do webhook, ID da entidade e trilha da automação. O script sem URL termina sem enviar nada. |
| O POST funciona, mas o Claude não avisa | Mesma pasta e terminal da variável exportada, configuração em /hooks e um pedido real para Bash. Reinicie a sessão após mudar o JSON. |
| A luz não restaurou | Trilha da ação scene.turn_on, disponibilidade da lâmpada e possível reinício do HA. Restaure os valores anotados pelo painel. |
Para encerrar o ensaio, saia do Claude e limpe a variável desse terminal:
unset HA_DEMO_WEBHOOK_URLSe não quiser manter o aviso, desative apenas a automação criada neste exercício e retire o hook da pasta de teste. Se quiser continuar usando, mantenha o script, a configuração e a URL privada disponíveis no ambiente em que inicia o Claude.
12
Guarde a base e escolha o próximo passo
Ao terminar, você tem um Home Assistant com dados persistentes, uma luz conferida, o ar integrado quando compatível e um painel que abre no celular. O aviso azul acrescenta um sinal físico ao pedido do Claude.
- Sei em qual computador está o Home Assistant e onde está a pasta config.
- Consigo identificar as entidades usadas no painel.
- Conferi cada comando com a resposta do aparelho.
- O aviso azul restaura o estado inicial e a aprovação continua comigo.
- Tenho os arquivos do projeto e um caminho de backup para a configuração.
Acrescente um aparelho por vez. Primeiro confira a integração e a resposta real; depois ajuste o painel. Para acesso fora de casa, o guia de Tailscale é um próximo passo. Para a TV que mostro no encerramento, siga o tutorial de Free My TV.
Referências
- Home Assistant Container em Linux, Docker Engine e Compose.
- Tuya e Gree Climate.
- Painéis, webhooks, cenas e trilhas e testes de automações.
- Hooks do Claude Code.
- Alerta físico de vd Brink, referência com MQTT e Node-RED. O exemplo deste guia usa um webhook local no Home Assistant.