Visão geral

Guia completo para montar um assistente de IA doméstico estilo Alexa usando Home Assistant no Raspberry Pi 5, com LLM via OpenRouter como cérebro e MCP Servers para integrar ferramentas externas (Gmail, Calendar, Slack, n8n etc.).

O LLM roda na nuvem (OpenRouter API), então o Pi 5 só precisa processar áudio local (STT/TTS) — sem necessidade de GPU.

Stack:

Hardware: Raspberry Pi 5 8GB
OS: Home Assistant OS
STT: Faster-Whisper (local)
TTS: Piper (local)
LLM: OpenRouter API — 400+ modelos disponíveis (Claude, GPT-4, Gemini, Llama…)
Ferramentas: MCP Servers

Por que OpenRouter? Uma única API key dá acesso a mais de 400 modelos. Você pode trocar de modelo a qualquer momento sem reconfigurar o HA, e comparar preços/qualidade facilmente.

Etapa 1 — Hardware necessário

Item	Detalhe	Custo aprox.
Raspberry Pi 5 8GB	Versão 8GB RAM	R$ 550–700
Fonte oficial Pi 5	27W USB-C (obrigatória)	R$ 80–120
Cartão SD ou SSD	64GB+ A2 ou SSD USB-C	R$ 80–200
Microfone USB	Ou ESP32-S3-BOX (Willow)	R$ 80–250
Caixa de som	USB ou P2 3.5mm	R$ 60–150
Cabo Ethernet	Recomendado no início	R$ 15–30

Melhor opção de hardware de voz: ESP32-S3-BOX-3 (~$50). Far-field mic, speaker embutido, touchscreen, roda Willow. Dispensa microfone e caixa separados.

Etapa 2 — Instalar Home Assistant OS

Baixar o Raspberry Pi Imager no site oficial do Raspberry Pi.
No Imager: Choose Device → Raspberry Pi 5 → Choose OS → “Other specific-purpose OS” → Home Assistant → Home Assistant OS (versão Raspberry Pi 5).
Selecionar o SD/SSD e clicar em Write.
Inserir o SD/SSD no Pi, conectar o cabo Ethernet e a fonte. Aguardar 5–10 minutos para o sistema inicializar.
Acessar no browser: http://homeassistant.local:8123

Se não funcionar via hostname, usar o IP direto: http://192.168.x.x:8123 (verificar no roteador qual IP o Pi recebeu).

Etapa 3 — Configuração inicial

Seguir o wizard: definir nome, usuário e senha.
Configurar Wi-Fi em Settings → System → Network (opcional — manter Ethernet no início).
Instalar add-ons essenciais em Settings → Add-ons → Add-on Store:
- Terminal & SSH — acesso ao terminal
- File editor — editar arquivos de config
- Samba share — acesso via rede

Instalar HACS (recomendado)

HACS é o repositório de integrações da comunidade. Via terminal SSH:

wget -O - https://get.hacs.xyz | bash -

Reiniciar o HA e seguir o wizard do HACS para conectar ao GitHub.

Etapa 4 — Pipeline de voz (STT + TTS)

O Whisper (STT) e o Piper (TTS) rodam localmente no Pi — o áudio nunca sai da rede.

Instalar Whisper (Speech-to-Text)

Settings → Add-ons → Add-on Store → buscar “Whisper” → instalar o add-on oficial da Nabu Casa.

Modelos disponíveis:

tiny — mais rápido (~2s), menos preciso
base — bom equilíbrio (~4s) ← recomendado para Pi 5
small — melhor qualidade (~8s)

Iniciar o add-on e ativar “Start on boot”.

Instalar Piper (Text-to-Speech)

Add-on Store → buscar “Piper” → instalar.

Voz em português:

pt_BR-faber-medium

Iniciar e ativar “Start on boot”.

Criar o assistente de voz

Settings → Voice Assistants → ”+ Add Assistant”:

Name: Casa (ou qualquer nome)
Conversation agent: Home Assistant (será trocado para OpenRouter na próxima etapa)
Speech-to-text: Whisper
Text-to-speech: Piper — pt_BR-faber-medium
Wake word: Nabu

Etapa 5 — Conectar OpenRouter

Integração nativa disponível a partir do Home Assistant 2025.8.

1. Criar conta e gerar API Key

Acessar openrouter.ai → criar conta → API Keys → “Create API Key”. Dar um nome à chave e configurar limites de billing para evitar surpresas.

2. Adicionar integração OpenRouter no HA

Settings → Devices & Services → ”+ Add Integration” → buscar “OpenRouter” → colar a API Key.

3. Adicionar conversation agent

Após criar a integração, clicar em ”+ Add conversation agent” e selecionar o modelo desejado.

Modelos recomendados para uso doméstico:

Modelo	ID no OpenRouter	Custo	Observação
Claude Sonnet 4	`anthropic/claude-sonnet-4`	~$3/M tokens	Melhor equilíbrio
GPT-4o mini	`openai/gpt-4o-mini`	~$0.15/M tokens	Mais barato
Gemini Flash 2.0	`google/gemini-flash-2.0`	~$0.10/M tokens	Rápido e barato
Llama 3.3 70B	`meta-llama/llama-3.3-70b-instruct`	~$0.20/M tokens	Open source

Para web search embutida, adicionar :online ao final do model ID, ex: anthropic/claude-sonnet-4:online.

4. Configurar o prompt do sistema

Nas opções do conversation agent, editar o prompt:

Você é um assistente doméstico pessoal chamado Nabu.
Responda sempre em português brasileiro.
Seja conciso e direto nas respostas de voz.
Você tem acesso aos dispositivos da casa e pode
controlá-los conforme solicitado.

5. Atualizar o assistente de voz

Settings → Voice Assistants → editar o assistente criado → mudar o Conversation Agent para o agent do OpenRouter → salvar.

Etapa 6 — Configurar MCP Servers

O HA pode ser tanto cliente MCP (consumir ferramentas externas) quanto servidor MCP (expor a casa para clientes externos).

HA como cliente MCP (adicionar ferramentas)

Settings → Devices & Services → ”+ Add Integration” → buscar “Model Context Protocol”.

Adicionar a URL do MCP server. Cada server adicionado vira tools disponíveis para o LLM.

MCP Servers populares para começar:

mcp-fetch — busca na web
mcp-google-calendar — eventos
mcp-gmail — e-mails
mcp-slack — mensagens
mcp-todoist — tarefas

Instalar via pip/npx numa máquina na rede e expor via SSE usando mcp-proxy.

HA como servidor MCP (expor para Claude Desktop / outros clientes)

Settings → Devices & Services → ”+ Add Integration” → buscar “Model Context Protocol Server”.

Configurar no claude_desktop_config.json:

{
  "mcpServers": {
    "homeassistant": {
      "command": "mcp-proxy",
      "args": ["http://homeassistant.local:8123/mcp_server/sse"],
      "env": {
        "API_ACCESS_TOKEN": "seu_token_aqui"
      }
    }
  }
}

Definir entidades expostas ao LLM

Settings → Voice Assistants → aba “Expose”. Marcar apenas as entidades que o LLM pode ver e controlar.

Etapa 7 — Wake word e hardware de voz

Opção A — Microfone USB direto no Pi

Instalar o add-on Wyoming Satellite. Configuração:

wake_word: openWakeWord
wake_word_model: hey_nabu
microphone_device: auto

Opção B — Smartphone como satélite (mais fácil)

Instalar o Home Assistant Companion no Android/iPhone. No app: Configurações → Companion App → “Use as voice satellite”. Sem hardware extra!

Opção C — ESP32-S3-BOX com Willow (recomendado)

O ESP32-S3-BOX-3 já vem com mic far-field, speaker e display. Instalar o firmware do Willow e apontar para o HA. Resposta em menos de 500ms.

Firmware: heywillow.io

Instalar openWakeWord

Add-on Store → buscar “openWakeWord” → instalar.

Modelos disponíveis:

hey_nabu — padrão HA
ok_nabu — alternativa
hey_jarvis

No assistente de voz, selecionar como “Wake word engine”.

Etapa 8 — Testar e ajustar

Testar via chat primeiro

No painel do HA, clicar no ícone de chat (canto superior esquerdo). Selecionar o assistente com OpenRouter. Testar:

“Que horas são?”
“Qual a temperatura lá fora?”
“Acenda a luz da sala”

Testar o pipeline de voz

Settings → Voice Assistants → assistente → botão de microfone. Falar um comando e verificar o texto transcrito e a resposta do Piper.

Problemas comuns

Problema	Solução
Whisper não reconhece	Verificar se o add-on está rodando. Testar com o modelo `tiny`.
LLM não responde	Verificar API key e saldo em `openrouter.ai/credits`.
Wake word não ativa	Verificar se openWakeWord está rodando e microfone detectado (`arecord -l`).
MCP não conecta	Verificar se o MCP server está acessível na rede (`curl http://ip:porta/sse`).
Erro ao adicionar conversation agent	Bug reportado no HA 2025.8.0 — atualizar para versão mais recente do HA.

Próximos passos

Nabu Casa Cloud — acesso remoto fora de casa (~$7/mês)
Zigbee2MQTT — adicionar dispositivos Zigbee
n8n + HA webhook — automações avançadas com fluxos no n8n
AI Tasks — criar automações com linguagem natural
Web search — adicionar :online ao model ID para busca na web embutida

Alisson's Notes

Explorador

Home Assistant com Claude API e MCP no Raspberry Pi 5