Liga a IA ao teu Home Assistant

Guia de início RepairGuyDK

Liga a IA ao teu Home Assistant+ Zigbee2MQTT Bonus

No fim, vais ter um Home Assistant novinho instalado, com o Claude AI ligado e o Zigbee2MQTT bem configurado, pronto para pôr a tua casa inteligente a funcionar.

LEMBRA-TE! Adiciona os routers à tua rede Zigbee PRIMEIRO (dispositivos ligados à corrente, por exemplo tomadas inteligentes e lâmpadas), para que a rede fique forte antes de começares a adicionar dispositivos a pilhas.

SONOFF Dongle Plus MG24, pen USB Zigbee com a caixa
✔ Testado com

SONOFF Dongle Plus MG24 (Silicon Labs EFR32MG24)

Deve funcionar também com a maioria das outras pens USB Zigbee.

Os coordenadores LAN e PoE não foram testados!

O que precisas
  • Um Home Assistant a funcionar, ou um PC e o RepairGuyDK Installer for Home Assistant para o instalares (vê o passo 0). Fora da Dinamarca, o instalador é vendido como ficheiro ISO para descarregar, que gravas tu numa pen USB com o Rufus ou o balenaEtcher. A pen USB já pronta só é vendida a clientes na Dinamarca.
  • Uma conta GitHub gratuita para o HACS. Cria-a já e inicia sessão.
  • Uma conta Claude (a gratuita chega para experimentar). Descarrega o Claude Desktop e inicia sessão com a tua conta.
  • Um destes dois caminhos (escolhes no passo 4):
    • Caminho 1: Nabu Casa (Home Assistant Cloud). Uma subscrição paga que faz o Claude funcionar em todo o lado, também no telemóvel e quando estás fora de casa.
    • Caminho 2: Um PC com Windows na mesma rede que o Home Assistant. Gratuito, mas só funciona em casa, no Claude Desktop.
Criar conta GitHub Criar conta Claude Descarregar o Claude Desktop

Já tens as contas e o Claude Desktop? Então salta esta parte.

Cada botão azul abre o Home Assistant num novo separador. Fecha o separador quando terminares o passo e volta a este guia.

  1. 0

    Já tens o Home Assistant a funcionar?

    O guia começa quando o Home Assistant já está a funcionar num PC em tua casa.

    ✅ Sim, já tenho Ótimo, então podes saltar a instalação. Ir para o passo 2 ↓
    💿 Não, ainda não Instala-o primeiro com o RepairGuyDK Installer for Home Assistant:
    1. Se compraste o ficheiro ISO, grava-o primeiro numa pen USB vazia com o Rufus (escolhe DD Image quando perguntar) ou o balenaEtcher. ⚠ Tudo o que está na pen é apagado. Se tens a pen USB da RepairGuyDK, salta este ponto.
    2. Liga a pen ao PC que vai ser o teu Home Assistant. ⚠ Todo o disco do PC é apagado.
    3. Na BIOS: UEFI ligado, Secure Boot desligado, Legacy/CSM desligado
    4. Arranca o PC a partir da USB (normalmente F9, F12, F11 ou Esc ao ligar) e escolhe a entrada UEFI
    5. Segue as instruções no ecrã e escreve SIM (em maiúsculas) quando te pedir
    6. Retira a pen, liga um cabo de rede e reinicia. Espera uns minutos e depois passa ao passo 1.
  2. 1

    Abre o Home Assistant e cria a tua conta

    Abre um browser no PC ou no telemóvel e vai a:

    http://homeassistant.local

    Escolhe o idioma, cria o teu utilizador e indica onde vives. Aponta a palavra-passe.

    Primeiro arranque: se a página mostrar "Preparing Home Assistant", espera uns minutos. O Home Assistant está a descarregar-se.

    O endereço não funciona? Usa antes o endereço IP. Aparece no ecrã do PC do teu Home Assistant, por exemplo http://192.168.1.50

  3. 2

    Instala o HACS

    O HACS é uma loja de apps extra para o Home Assistant. Precisamos dela para obter a ligação à IA.

    Já tens o HACS? Se o HACS aparece no menu à esquerda no Home Assistant, passa diretamente para o passo 3.

    A. Adicionar o HACS ao Home Assistant
    1. Da primeira vez que clicas num botão destes, a página pede o endereço do teu Home Assistant. O campo já tem http://homeassistant.local:8123. Apaga-o, escreve http://homeassistant.local sem :8123 e clica em Save. Se não funcionar, escreve o endereço IP, por exemplo http://192.168.1.50. Aparece no ecrã do PC do teu Home Assistant. Depois clica em Open link.
    2. O teu Home Assistant pergunta se queres adicionar o repositório. Clica em Adicionar. Um repositório é apenas o endereço de uma loja extra.
    3. Vai a Definições › Aplicações › Instalar aplicação e escreve HACS no campo de pesquisa em cima
    4. Abre Get HACS, clica em Instalar e depois em Iniciar. Só corre durante alguns segundos. É perfeitamente normal aparecer como parado a seguir.
    5. Reinicia o Home Assistant: vai a Definições, clica nos três pontos no canto superior direito e escolhe Reiniciar o Home Assistant. Espera 1 a 2 minutos até a página voltar.
    B. Ativar o HACS
    1. Clica no botão azul Adicionar integração no canto inferior direito
    2. Escreve HACS no campo de pesquisa e escolhe HACS
    3. Marca todas as caixas e clica em Submeter
    4. Recebes um código de 8 caracteres e uma ligação para o GitHub. Abre a ligação, inicia sessão no GitHub, introduz o código e clica em Authorize HACS
    5. Volta ao Home Assistant e clica em Terminar. Prime F5 e o HACS aparece no menu à esquerda.
  4. 3

    Instala a ligação à IA (HA-MCP)

    O HA-MCP é o que permite ao Claude falar com a tua casa. Fica dentro do Home Assistant.

    A. Obter o HA-MCP no HACS
    1. O HACS abre a página do HA-MCP Custom Component. Se perguntar se queres adicionar o repositório, clica em Adicionar.
    2. Clica em Download no canto inferior direito e depois novamente em Download
    3. Reinicia o Home Assistant: vai a Definições, clica nos três pontos no canto superior direito e escolhe Reiniciar o Home Assistant. Espera 1 a 2 minutos até a página voltar.
      NÃO saltes o reinício! Sem ele, não vais encontrar o HA-MCP no passo seguinte.
    B. Ativar o HA-MCP
    1. Clica no botão azul Adicionar integração no canto inferior direito
    2. Escreve HA-MCP no campo de pesquisa e escolhe HA-MCP Custom Component
    3. Escolhe HA-MCP Server e clica em Submeter
    4. Agora pede um Administrator access token. Deixa a janela aberta e abre o Home Assistant num novo separador (Ctrl+T)
    5. No novo separador: clica no teu nome no fundo do menu à esquerda, escolhe Segurança e desce até Tokens de acesso de longa duração
    6. Clica em Criar token, escreve o nome HA-MCP e clica em OK. Copia logo o código, porque só é mostrado uma vez
    7. Volta ao separador do HA-MCP Server, cola o código em Administrator access token, deixa vazios os campos de utilizador e palavra-passe e clica em Submeter
    8. Aparece uma mensagem a dizer que o servidor arrancou e o HA-MCP surge no menu à esquerda. Está a funcionar.

    Importante: Só pode haver um HA-MCP no teu Home Assistant. Vai a Definições › Aplicações e procura a app Home Assistant MCP Server. Se estiver lá, abre-a e clica em Desinstalar antes de continuares. Se não estiver, não precisas de fazer nada.

  5. 4

    Escolhe o teu caminho e ativa o acesso

    O HA-MCP começa totalmente fechado, para que ninguém se consiga ligar. Aqui abres apenas o caminho que queres usar.

    Abrir o HA-MCP Server

    Ao lado de HA-MCP Server, clica na roda dentada. Depois faz apenas o que está indicado no teu caminho:

    Caminho 1: Com Nabu Casa Funciona no claude.ai, na app Claude no PC e no telemóvel, também quando estás fora de casa.
    1. ⚙️ Clica na roda dentada ao lado de HA-MCP Server. Está no lado direito da linha.
    2. Desce para lá de Home Assistant URL (advanced) e marca Remote access via webhook
    3. Deixa Authentication mode em Sign in with Home Assistant (OAuth)
    4. Clica em Submeter e volta a clicar na roda dentada
    5. Copia o endereço que contém ui.nabu.casa. Passa ao passo 5.
    Caminho 2: Só em casa, gratuito Funciona no Claude Desktop num PC com Windows na tua rede de casa.
    1. ⚙️ Clica na roda dentada ao lado de HA-MCP Server. Está no lado direito da linha.
    2. Clica no campo Network access (diz "This machine only (loopback)") e escolhe Local network
    3. Clica em Submeter e volta a clicar na roda dentada
    4. Copia o endereço completo que contém :9584/private_, incluindo http:// e :9584, por exemplo http://192.168.1.50:9584/private_XJtn3QszNpRXaYYmM6YeVA. Não pode começar por 127.0.0.1. Passa ao passo 6.

    Não mexas nos outros campos da janela.

    Não aparece nenhum endereço com ui.nabu.casa depois do Caminho 1? Então o Nabu Casa não está ativo. Segue o Caminho 2.

    O endereço começa por 127.0.0.1 depois do Caminho 2? Então o Local network não ficou guardado e o Claude não consegue chegar ao teu Home Assistant. Clica de novo na roda dentada, escolhe Local network em Network access, clica em Submeter e abre a roda dentada mais uma vez. Agora o endereço começa pelo IP do teu Home Assistant, por exemplo http://192.168.1.50:9584/private_...

    Fecha a janela com o X depois de copiares o endereço.

    O endereço é a chave da tua casa. Quem o tiver pode controlar tudo. Não o partilhes e desfoca-o em capturas de ecrã e vídeos.

  6. 5
    Só Caminho 1: Nabu Casa

    Dá o endereço ao Claude

    Podes fazê-lo no browser em claude.ai ou no Claude Desktop. Os botões são os mesmos. Só precisas de o fazer num dos sítios.

    A ligação fica guardada na tua conta Claude. Depois funciona em todo o lado onde tiveres sessão iniciada: no browser, no Claude Desktop e no telemóvel.

    Abrir o claude.ai
    1. Abre o claude.ai no browser ou abre o Claude Desktop. Inicia sessão se te for pedido.
    2. Clica no teu nome no canto inferior esquerdo e escolhe Definições (Settings).
    3. No menu à esquerda, clica em Conectores (Connectors).
    4. Clica no botão para adicionar um conector personalizado (custom connector).
    5. No campo Nome (Name), escreve Home Assistant.
    6. No campo URL, cola o endereço com ui.nabu.casa do passo 4 (clique direito e escolhe Colar).
    7. Deixa todos os outros campos vazios e clica em Adicionar (Add).
    8. Agora abre-se o teu Home Assistant. Inicia sessão com o teu próprio utilizador do Home Assistant e clica em Permitir (Allow). O Claude está agora ligado.

    Terminaste o Caminho 1? Salta o passo 6 e passa ao passo 7.

  7. 6
    Só Caminho 2: Localmente no teu PC

    Executa o programa da RepairGuyDK

    O programa liga o Claude Desktop ao teu Home Assistant. Não precisas de editar ficheiros. Se ainda não tens o Claude Desktop, descarrega-o e inicia sessão primeiro.

    Descarregar o Claude Desktop Abrir o Claude Desktop

    Se já tens o Claude Desktop, clica em Abrir o Claude Desktop. Se o browser perguntar se pode abrir o Claude, clica em Abrir. Se não o tens, clica primeiro em Descarregar o Claude Desktop.

    📂 Encontra o programa na pen USB

    Abre a unidade REPAIRGUYDK da tua pen USB no Explorador de Ficheiros. Entra na pasta do teu idioma e depois na pasta Ligacao-IA:

    REPAIRGUYDK›Portugues›Ligacao-IA›INICIAR-AQUI

    Não tens a pen à mão? Descarrega aqui o programa como ficheiro zip. Clica com o botão direito no ficheiro zip e escolhe Extrair Tudo antes de continuares.

    1. Faz duplo clique em INICIAR-AQUI
    2. Se o Windows mostrar "O Windows protegeu o PC", clica em Mais informações e depois em Executar mesmo assim
    3. Cola o endereço com :9584/private_ do passo 4 (clique direito na janela para colar) e prime Enter
    4. Se o Claude Desktop estiver aberto, o programa pergunta: O programa pode fechar o Claude Desktop agora? (s/n). Escreve a letra s (de sim) e prime Enter. O programa instala o que for preciso e volta a abrir o Claude.
    5. No Claude Desktop, confirma em Definições › Programador (Settings › Developer) que o home-assistant aparece como running
  8. 7

    Experimenta

    1. Inicia uma nova conversa:
      Caminho 1: no claude.ai, no Claude Desktop ou no telemóvel
      Caminho 2: no Claude Desktop
      Escolhe o ícone de chat (verde) no topo do Claude Desktop, não o ícone de código (vermelho).Escolhe o ícone de chat (verde) no topo do Claude Desktop, não o ícone </> (vermelho).
    2. Escreve uma destas frases e prime Enter:
    • Consegues ver o meu Home Assistant?
    • Faz uma verificação do estado do meu Home Assistant.

    Da primeira vez, o Claude pergunta se pode usar o Home Assistant. Clica em Permitir (Allow).

Extra: MQTT e Zigbee2MQTT

Tens um dongle Zigbee, por exemplo Home Assistant Connect ZBT ou SONOFF? Então podes instalar o MQTT e o Zigbee2MQTT com quatro cliques. Cada botão abre a página certa no teu próprio Home Assistant.

O botão mostra a página My Home Assistant com http://homeassistant.local:8123 no campo? Apaga o :8123 para ficar http://homeassistant.local (ou o endereço IP, por exemplo http://192.168.1.50) e clica em Save. Isto acontece quando usas um browser ou telemóvel diferente do passo 2, e só tens de o fazer uma vez por browser.

  1. A. Instalar o Mosquitto (MQTT)Clica em Instalar, liga todos os interruptores e clica em Iniciar.
  2. B. Configurar o MQTTConfirma que queres configurar o MQTT, escolhe "Use the official Mosquitto Mqtt Broker app" e clica em Terminar quando aparecer Sucesso.
  3. C. Adicionar o Zigbee2MQTTClica em Adicionar quando perguntar se queres adicionar o repositório.
  4. D. Instalar o Zigbee2MQTTClica em Instalar e liga todos os interruptores. NÃO cliques em Iniciar! O Claude inicia-o por ti no último passo.

Último passo: Liga o dongle Zigbee ao PC do teu Home Assistant. Inicia uma nova conversa com o Claude e escreve:

Escreve isto ao Claude (copiar/colar)Configura o Zigbee2MQTT com o meu dongle. Pergunta-me que dongle tenho. Encontra a porta (de preferência a que começa por /dev/serial/by-id/) e o tipo de adaptador certo, e guarda-os em serial nas definições da app Zigbee2MQTT como port e adapter. Lê de novo as definições e confirma que ficaram guardadas. Depois inicia a app e diz-me que porta e adaptador escolheste.

Se a configuração automática do dongle falhar, é fácil de resolver: Clica em Zigbee2MQTT no menu à esquerda no Home Assistant. Provavelmente vais ver uma página chamada Onboarding com uma caixa vazia em cima. Clica na caixa e escolhe o teu adaptador no menu (provavelmente perto do fim). Depois desce até ao fim da página e clica em Submit. O Zigbee2MQTT deve agora arrancar corretamente após alguns segundos. Se vires um ícone estranho, prime F5 para atualizar a página.

Zigbee2MQTT Onboarding: 1 adapter, 2 SONOFF, 3 Submit

🎉

Parabéns, a tua casa inteligente está pronta!

O Home Assistant está a funcionar, o Claude está ligado e o Zigbee2MQTT está pronto para os teus dispositivos. Muito bem!

Próximo passo: Adiciona primeiro os teus routers (dispositivos ligados à corrente), para que a rede Zigbee fique forte antes de entrarem os dispositivos a pilhas.

Experimenta escrever ao Claude: "Cria uma automação que acende a luz do corredor quando o sol se põe"

Aproveita! Da RepairGuyDK 🔧

Se algo correr mal

Que caminho devo escolher?

Se tens Nabu Casa (Home Assistant Cloud), segue o Caminho 1. É o mais fácil e o Claude funciona também no telemóvel e quando estás fora de casa. Se não tens Nabu Casa, segue o Caminho 2. É gratuito, mas só funciona no Claude Desktop num PC em casa. Podes ver se tens Nabu Casa em Definições › Home Assistant Cloud:

Se mostrar que tens sessão iniciada e estás ligado, tens Nabu Casa. Segue o Caminho 1.

Se te convidar a controlar a casa quando estás fora, não tens Nabu Casa. Segue o Caminho 2.

Os botões abrem uma página que não responde

Então o teu browser guardou um endereço errado para o teu Home Assistant, normalmente com :8123 no fim. Abre my.home-assistant.io/redirect/_change, apaga o que lá está, escreve o endereço sem :8123 (por exemplo http://homeassistant.local ou http://192.168.1.50) e clica em Save. Depois experimenta o botão outra vez.

O homeassistant.local não abre

Alguns routers e telemóveis não conseguem encontrar o nome. Usa o endereço IP que aparece no ecrã do PC do teu Home Assistant. Também o podes encontrar na lista de dispositivos ligados do teu router.

Não encontro o Get HACS nem o HA-MCP
  • Get HACS: prime F5 na loja de apps. Se não ajudar, clica nos três pontos no canto superior direito e escolhe Procurar atualizações.
  • HA-MCP em Adicionar integração: esqueceste-te do reinício do passo 3. Reinicia o Home Assistant e tenta outra vez.
O Claude não vê o meu Home Assistant
  • Caminho 1: confirma que Remote access via webhook está marcado na roda dentada do HA-MCP Server, que copiaste o endereço completo com ui.nabu.casa e que o acesso remoto está ativo em Home Assistant Cloud. Apaga o conector no claude.ai e adiciona-o outra vez.
  • Caminho 2: confirma que Network access está em Local network na roda dentada do HA-MCP Server. Fecha o Claude por completo em Ficheiro › Sair (File › Exit), também a partir do ícone junto ao relógio, e volta a abri-lo. O teu PC tem de estar na mesma rede que o Home Assistant. Executa de novo o programa da RepairGuyDK com o endereço que contém :9584. Depois confirma no Claude Desktop, em Definições › Programador, que o home-assistant aparece na lista.
  • Os dois caminhos: confirma que o HA-MCP aparece no menu à esquerda no Home Assistant. Se o Claude vê as tuas coisas mas não as consegue alterar, clica na roda dentada ao lado de HA-MCP Server e confirma que o Read Only Mode está desligado (cinzento).
    Read Only Mode no HA-MCP Server com o interruptor desligado, assinalado a vermelho
O Claude diz que está a correr na nuvem e não vê o meu Home Assistant

Então fizeste a pergunta numa tarefa que corre na nuvem (por exemplo Cowork) e não numa conversa normal. Essa tarefa não consegue ver a ligação no teu PC, mesmo que o home-assistant apareça como running em Definições › Programador. Isto não tem nada a ver com a tua subscrição.

Escolhe o ícone de chat (verde) no topo do Claude Desktop, não o ícone </> (vermelho).

Escolhe o ícone de chat (verde) no topo do Claude Desktop, não o ícone de código (vermelho).

  • Escolhe Chat no Claude Desktop e clica em Nova conversa (New chat).
  • Clica em + na caixa de mensagem e confirma que o home-assistant está ligado.
  • Pergunta outra vez, por exemplo "Consegues ver o meu Home Assistant?", e clica em Permitir quando o Claude pedir.

Se funcionar, a resposta mostra que o Claude usou o home-assistant. Se o Claude continuar a dizer que está a correr na nuvem, estás no tipo de conversa errado.

Onde está o ficheiro de definições do Claude Desktop? (Caminho 2)

O programa da RepairGuyDK encontra o ficheiro sozinho, por isso normalmente não precisas de o procurar. Se o quiseres ver, abre o Claude Desktop, vai a Definições › Programador e clica em Editar configuração (Edit Config). O ficheiro chama-se claude_desktop_config.json.

  • Versões mais recentes do Claude Desktop para Windows: C:\Users\OTeuNome\AppData\Local\Claude-Data\claude_..., em que a pasta termina com um código diferente em cada PC
  • Versões mais antigas e muitos guias online: %APPDATA%\Claude
  • O AppData é uma pasta oculta. Escreve o endereço diretamente na barra de endereço do Explorador de Ficheiros ou ativa os itens ocultos em Ver.

O ficheiro pertence ao teu utilizador do Windows, não à tua conta Claude. Se alternares entre várias contas Claude no mesmo utilizador do Windows, todas ficam com a mesma ligação. Para as manteres separadas, usa um utilizador do Windows diferente.

É seguro?

O HA-MCP começa totalmente fechado até abrires o teu caminho no passo 4. O endereço contém uma chave secreta longa criada pelo próprio HA-MCP. Com o Caminho 2, tudo corre apenas na tua própria rede. Com o Caminho 1, a ligação é encriptada através do Nabu Casa e o Claude também tem de iniciar sessão com o teu utilizador do Home Assistant antes de ter acesso. O Claude pede autorização antes de usar o Home Assistant. Se partilhaste o endereço por engano, apaga o HA-MCP Server em Dispositivos e serviços e adiciona-o outra vez; assim recebes um novo.

Posso usar o ChatGPT em vez disso?

Talvez, mas não está testado e dá mais trabalho do que com o Claude. O ChatGPT só deixa adicionar o teu próprio conector com o Plus ou superior, não com o gratuito nem com o Go. Também tens de ativar o Developer mode no ChatGPT no browser. Só funciona com o Caminho 1 (Nabu Casa), porque o ChatGPT não consegue usar o programa da RepairGuyDK do Caminho 2. A OpenAI também limita o que o ChatGPT pode alterar através de um conector destes nos planos mais baratos. Este guia foi feito e testado para o Claude, que já funciona com a conta gratuita.

O Claude gratuito chega?

Para experimentar, sim. O Claude gratuito funciona com o Home Assistant e, com o Caminho 1, podes adicionar um conector personalizado. O plano gratuito tem um limite de utilização por cada 5 horas. As tarefas do Home Assistant gastam bastante, porque o Claude lê os teus dispositivos, automações e registos. "Desliga a luz da sala" é uma tarefa pequena, enquanto "faz um dashboard" pode gastar a maior parte de uma quota gratuita. Quando o limite é atingido, o Claude pede-te para esperares. Não é um erro.

Se quiseres usar o Claude para criar automações, dashboards ou instalar coisas como o Zigbee2MQTT, recomendamos o Claude Pro, que dá pelo menos 5 vezes mais utilização. Vê os preços atuais em claude.com/pricing.

Passei para o Claude Pro. Tenho de alterar alguma coisa?

Não. Se fizeres o upgrade na mesma conta Claude, tudo continua a funcionar logo. Com o Caminho 1 a ligação fica guardada na tua conta Claude e com o Caminho 2 fica no teu PC. Um upgrade não altera nenhuma delas.

Se, em vez disso, criaste uma conta Claude nova para o Pro, com o Caminho 1 tens de adicionar o conector outra vez como no passo 5. O Caminho 2 continua a funcionar, porque acompanha o teu PC. Se quiseres, fecha o Claude Desktop por completo em Ficheiro › Sair (File › Exit) e volta a abri-lo depois do upgrade.

Posso desfazer tudo?

Sim. Apaga o HA-MCP Server em Definições › Dispositivos e serviços e remove o conector no claude.ai. O programa da RepairGuyDK guarda uma cópia de segurança das definições do Claude antes de alterar seja o que for.

RepairGuyDK · Made in Spain With Danish Calmness