跳转到教程正文

把 Home Assistant 连接到 Noma，用一句话控制你的家

Noma 是一款具备长期记忆的 AI 智能家居助手。Home Assistant 负责连接和管理兼容设备，Noma 通过它查询家庭状态、执行自然语言设备控制请求，并在启用记忆后参考你的个人偏好。

本教程从环境准备讲到首次设备控制，无需登录即可阅读。实际连接家庭和使用设备功能时，请登录你的 Noma 账号。

开始前需要准备什么

  • 一个 Noma 账号，以及用于打开接入向导的 Windows、macOS 或 Linux 电脑。
  • 一台可持续运行 Docker 的设备，用于运行 Noma 本地连接服务；它需要能访问你的 Home Assistant 和互联网。
  • 一个可正常访问的 Home Assistant 实例。没有实例时，可以按下一节先安装。
  • 至少一个已经接入 Home Assistant 的设备，用于验证查询或控制。先确认它能在 Home Assistant 中正常使用。

已有 Home Assistant OS、NAS 或其他实例的用户，可以直接复用。Home Assistant 本体不必和连接服务安装在同一台设备上，关键是连接服务能访问它。

1. 安装或复用 Home Assistant

如果你已经能打开 Home Assistant 并控制设备，跳到下一节即可。首次安装可以参考Home Assistant 官方安装指南，选择适合硬件的方式。

先安装并启动 Docker

如果选择用 Docker 安装 Home Assistant，需要先完成下面的准备。Docker 已安装且正在运行的用户，可以直接检查是否可用。

  1. 选择你的操作系统并按照官方指引安装：Windows、macOS、Linux。Mac 用户需选择与 Apple 芯片或 Intel 芯片对应的版本。
  2. Windows 用户按照安装指引完成 WSL 2 等环境配置；如提示重启，重启后再继续。
  3. Windows 和 macOS 用户安装后打开 Docker Desktop，等待引擎启动完成，并在后续使用时保持运行。Linux 用户按所选发行版的安装指引启动 Docker 服务，并完成运行命令所需的权限配置。
  4. Windows 打开 PowerShell，macOS 或 Linux 打开终端，运行下面的检查命令。
docker info

能正常看到 Client 和 Server 信息后，再继续安装 Home Assistant。若提示找不到 docker 命令，请确认安装完成并重新打开终端；若提示无法连接 Docker 引擎，请先启动 Docker Desktop 或 Docker 服务；若提示权限不足，请按对应系统的官方指引处理权限。

再用 Docker 安装 Home Assistant

确认 Docker 可用后，在同一个终端执行以下与 Noma 安装向导一致的命令：

docker run -d --name homeassistant --restart unless-stopped -e TZ=Asia/Shanghai -p 8123:8123 -v homeassistant_config:/config ghcr.io/home-assistant/home-assistant:stable

该命令将配置保存在 Docker 的homeassistant_config数据卷中。已有同名容器或 8123 端口被占用时，先检查现有实例，不要重复安装。

首次启动需要下载镜像和初始化。就绪后，在运行 Home Assistant 的电脑上打开http://localhost:8123，创建家庭和本地用户。若从另一台设备访问，使用该电脑的局域网 IP，例如http://192.168.1.100:8123。

在 Home Assistant 的「设置 → 设备与服务」中接入你的设备，并先测试手动控制。Docker 的网络环境可能影响自动发现；设备接入方式和兼容性请以对应集成的官方说明为准。

2. 建立 Noma 连接

  1. 登录 Noma，在电脑上打开「设置 → Home Assistant」，点击「我已安装 Home Assistant」。
  2. 进入「建立连接」。复制页面为当前账号生成的连接命令，在准备好的 Docker 设备终端中运行。
  3. 默认地址为http://host.docker.internal:8123，用于从连接容器访问宿主机上的 Home Assistant。若你的实例在 NAS、另一台设备上，或该地址不可达，展开「自定义 Home Assistant 地址」，填写容器可访问的本地 HTTP 地址，再点击「重新生成连接命令」并运行新命令。
  4. 回到 Noma 点击「我已运行命令，检测连接」。出现「Noma 连接已建立」后，进入授权步骤。

连接命令与账号关联，请使用你自己设置页生成的最新命令。Home Assistant 和本地连接服务需要保持运行；如果页面提示连接服务暂未开放，请等待服务可用后再继续。

3. 创建长期访问令牌并授权

  1. 打开你自己的 Home Assistant，进入「个人资料 → 安全 → 长期访问令牌」。
  2. 点击「创建令牌」，填写便于识别的名称，例如「Noma」，复制生成的令牌。
  3. 返回 Noma 的「授权 Home Assistant」步骤，将令牌粘贴到「Home Assistant 长期访问令牌」输入框。
  4. 点击「验证并完成连接」，按页面反馈确认是否成功。

令牌用于让 Noma 访问你的 Home Assistant，请仅填写到自己的 Noma 设置页，不要发在公开截图或帖子中。停止授权时，可在 Home Assistant 中删除对应令牌。有关令牌机制可查看Home Assistant 官方认证说明。

4. 验证设备，开始第一次对话

连接完成后，先在Noma「家」页面核对设备名称、房间和状态，再打开Noma 对话页。下面是可按你家设备名称调整的请求示例：

  • 查询状态：「客厅灯现在是开着还是关着？」
  • 首次控制：「帮我打开客厅灯。」
  • 调整空调：「把卧室空调设为制冷，温度调到 26 度。」

查看 Noma 返回的工具执行结果，并核对设备实际状态。查询温度需要已接入对应传感器，调温需要空调实体支持该功能，具体操作取决于设备能力和授权。

再让 Noma 了解你的偏好

启用自动记忆后，你可以告诉 Noma：「我睡觉时喜欢卧室温度保持在 26 度。」它可在后续相关对话中参考保存的偏好；你可以在设置中检查和删除记忆。保存偏好本身不等于创建定时任务，也不会让设备自动按时执行。

连接问题排查

打不开 Home Assistant 页面？
先确认 Home Assistant 已启动。如果用 Docker 安装，检查 Docker 是否正在运行，以及 homeassistant 容器是否正常启动。localhost 指的是当前设备；从另一台电脑或手机访问时，应使用 Home Assistant 所在设备的局域网地址，并确认 8123 端口可达。
Noma 提示「暂未检测到连接」？
确认已执行当前账号设置页生成的连接命令，Docker 和本地连接服务保持运行。若 Home Assistant 不在同一台设备上，展开「自定义 Home Assistant 地址」，填写连接容器能够访问的 HTTP 地址，例如 http://192.168.1.100:8123，重新生成并运行连接命令，再点击「重新检测」。Linux 环境尤其需要确认容器能否访问目标地址，不要直接假设 host.docker.internal 可用。
令牌验证失败？
确认连接已经建立，令牌来自你要连接的那一个 Home Assistant 实例，复制时没有遗漏字符。如果令牌已删除或失效，在该实例中重新创建，然后回 Noma 再次验证。
连接成功，但找不到或无法控制设备？
先在 Home Assistant 中确认设备已经接入、在线，并可手动操作。检查设备名称、房间和支持的功能；例如只有温度传感器时，不能执行空调调温。回到 Noma 的「家」页面刷新状态，再使用明确的设备名称发出请求。
手机可以完成接入吗？
当前 Noma 接入向导需要在电脑上完成部署和配置，并在可运行 Docker 的设备上执行连接命令。完成连接后，可以在手机上登录同一 Noma 账号使用家庭功能。
没有智能设备，也能体验吗？
可以先体验 Noma 对话。设备查询和控制需要完成 Home Assistant 接入；长期记忆需启用相应设置，保存的记忆可在产品中查看、管理和删除。
Noma Home Assistant 接入教程：连接设备与首次 AI 控制