home-assistant-mcp

home-assistant-mcp

一个 Model Context Protocol（MCP）服务，让编码 Agent——Cursor、VS Code（Copilot）、Claude Desktop 以及其他支持 MCP 的工具——直接与 Home Assistant 及（可选的）ESPHome 仪表板通信。

无需将实体 ID、YAML 和当前值复制粘贴到 Agent 中，Agent 就能自行发现实体、读取实时状态、渲染模板、调用服务和编辑自动化，并不断迭代，直到代码真正可用。

在 Claude Code 中，四个侧边窗格会实时展示 Claude 对家中所做的操作：它正在处理的自动化、正在构建的 ESPHome 设备、家中的健康评分，以及一个可用的仪表板。只需一条命令即可安装全部四项（见下文）。

它属于 Vome 系列，是 VomeHome（托管式 Home Assistant）的开源配套项目。任何 Home Assistant 用户都可以独立使用。

---

为什么

如今，典型的“更改自动化”流程是：告诉 Agent 有哪些实体，粘贴它们的当前值和 YAML，应用更改，然后手动检查是否生效。使用此服务后，Agent 可以完成所有这些操作：

• 查看 — 列出实体／区域／设备，读取确切状态和属性，获取历史记录和日志簿。
• 试验 — 针对实时状态渲染 Jinja 模板、检查配置、读取错误日志。
• 更改 — 调用服务、创建／更新／删除／触发自动化；对于 ESPHome，还可以编辑、验证、编译并刷写设备固件。

默认情况下，所有写入操作均禁用，并受明确的安全策略限制（参见安全性）。

---

工具

Home Assistant — 读取

工具	描述
ha_get_config	核心配置：版本、位置、时区、已加载的组件。
ha_list_entities	列出实体（按域筛选、全文搜索、按区域筛选）。
ha_get_state	一个或多个实体的完整状态和属性。
ha_get_history	指定时间范围内的历史状态变化。若只提供开始时间，则会一直查询到当前时间（Home Assistant 本身只会查询开始时间之后的 24 小时）；ha_get_logbook 也有相同行为。
ha_list_services	可用服务（以及指定域对应的字段）。
ha_list_areas	区域（房间／分区）。
ha_list_devices	设备注册表（按区域筛选／搜索）。
ha_get_entity_registry	注册表元数据：平台、区域、设备、是否已禁用／隐藏。
ha_render_template	针对实时状态渲染 Jinja2 模板。
ha_list_helpers	列出已存储的辅助工具（input_boolean、input_number、counter、timer 等）。
ha_list_automations	列出自动化及其 entity_id、唯一 ID、状态和上次触发时间。
ha_get_automation	完整的自动化配置（触发器／条件／操作）。
ha_check_config	验证配置（检查配置）。
ha_get_system_log	去重后的结构化错误——级别、日志记录器、来源、次数、首次／最后一次出现时间。请从这里开始。
ha_get_error_log	查看 Home Assistant 原始错误日志的末尾内容。
ha_get_supervisor_log	加载项／Core／Supervisor／主机日志（HAOS 或 Supervised）。
ha_list_media_files / ha_read_media_file	只读查看 /media：保存的摄像头快照会以图像形式返回（需要 ha:files，且家中的 Vome 加载项版本为 0.3.66 / 集成版本为 0.9.51）。
ha_camera_image	获取摄像头当前的静态图像，Agent 可以查看。通过 VomeHome 使用时，需要勾选 Cameras。
ha_camera_frame	将摄像头静态图像解码并缩小为 RGB 像素网格，供能以文本绘图的客户端使用。
ha_view_snapshot	一次调用即可获取仪表板视图显示的全部内容：状态、渲染后的模板、精简历史记录和摄像头画面。供仪表板客户端使用。
ha_watch_states	等待状态变化，而不是轮询：家中的 Vome 组件会在状态变化时通过 VomeHome 发送通知。
ha_get_logbook	以易读格式显示日志簿条目。
ha_get_energy_prefs	Energy 仪表板的设置（电网、太阳能、电池、燃气、水、跟踪的设备），并使用仪表板自身的验证机制。
ha_list_traces	最近的自动化／脚本运行记录及每次运行停止的原因。
ha_get_trace	某次运行的逐步详情，其中 failed_at 指明了阻塞步骤。

Home Assistant — 写入（受写入权限控制）

写入权限控制取决于运行模式。在 direct 模式下，MCP 是唯一的防护机制， 因此在设置 HA_ALLOW_WRITE=true 前，这些操作都会被拒绝。在 brokered 模式下，你的 VomeHome API 密钥具有针对每个实例的 ha:write / ha:config 作用域，且由服务端强制执行，因此客户端标志只是可选的本地限制。

工具	描述
ha_call_service	调用任意服务（turn_on、set_temperature，……）。
ha_clear_system_log	清空结构化错误存储（只需设置 HA_ALLOW_WRITE）。
ha_set_log_level	在运行时更改某个集成的日志级别（只需设置 HA_ALLOW_WRITE）。
ha_set_automation	创建或更新自动化（还需要设置 HA_ALLOW_CONFIG_WRITE）。
ha_set_helper	创建或更新辅助项——无需修改 configuration.yaml，也无需重启。
ha_read_config_file	读取配置目录下的文件——默认读取文本；对于二进制资源，可设置 encoding: 'base64'（需要 ha:files）。
ha_write_config_file	替换配置目录下的文件——默认写入文本；对于二进制资源，可设置 encoding: 'base64'；会检查配置，若检查失败则还原文件（需要 ha:files）。
ha_delete_config_file	删除配置目录下的一个文件。绝不删除目录，也绝不删除 configuration.yaml、secrets.yaml 或 Home Assistant 的数据库。与写入操作一样，可指定目标家庭（需要 ha:files，且家庭上的 Vome add-on 版本为 0.3.55 / integration 版本为 0.9.39）。
ha_edit_config_file	原地修改文本文件的部分内容：精确查找并替换，每项都必须且只能匹配一次；随后执行与写入相同的检查和还原。适用于修改大文件中的三行内容（需要 ha:files）。
ha_list_config_files	列出配置目录下的文件夹内容（需要 ha:files）。
ha_move_config_file	移动或重命名配置目录下的一个文件，并沿途创建文件夹；除非明确要求，否则不会覆盖文件。与写入操作一样，可指定目标家庭（需要 ha:files，且 Vome add-on 版本为 0.3.66 / integration 版本为 0.9.51）。
ha_delete_helper	删除已存储的辅助项。如果 ID 看起来与 configuration.yaml 中的辅助项共用，则会拒绝删除，因为 Home Assistant 会连同该实体一起移除。
ha_delete_automation	删除自动化（还需要设置 HA_ALLOW_CONFIG_WRITE）。
ha_get_script / ha_set_script / ha_delete_script	按 ID 操作脚本，方式与自动化相同：将多个自动化共用的步骤放入一个脚本中。写入操作需要设置 HA_ALLOW_CONFIG_WRITE。
ha_update_entity	在注册表中重命名实体、更改 ID、移动实体、更改图标、禁用实体或隐藏实体（需要 HA_ALLOW_CONFIG_WRITE）。
ha_update_device	重命名设备、将其移至某个区域、禁用设备或设置其标签（需要 HA_ALLOW_CONFIG_WRITE）。
ha_expose_entities	列出或更改 Assist、Alexa 和 Google Assistant 可查看和控制的内容；列出只需读取权限（更改需要 HA_ALLOW_CONFIG_WRITE）。
ha_set_energy_prefs	更改 Energy 仪表板的设置；传入的每个列表都会完整替换对应列表，然后进行验证（需要 HA_ALLOW_CONFIG_WRITE）。
ha_get_statistics	按 5 分钟至 1 个月的时间范围读取长期统计数据（即 Energy 仪表板绘制的数据）；largest_changes 会列出变化最大的分桶，与 Outliers 按钮类似。
ha_adjust_statistic	按新值或调整量修正某项统计数据中的一个 5 分钟分桶，操作方式与 Developer Tools → Statistics 相同（需要 HA_ALLOW_CONFIG_WRITE）。
ha_remove_entity	移除注册表中已失效的条目（需要 HA_ALLOW_CONFIG_WRITE）。
ha_matter_reinterview	执行 Matter 设备页面中的重新访谈操作，适用于固件更新后端点发生变化的设备（需要 HA_ALLOW_CONFIG_WRITE）。
ha_trigger_automation	立即手动运行自动化。
ha_reload_automations	重新加载自动化，无需重启。

Lovelace 仪表盘（直接连接 HA 或由 VomeHome 代理）

工具	功能
ha_list_dashboards	列出仪表盘（url_path、标题、模式、侧边栏）。
ha_get_dashboard	读取单个仪表盘的完整配置（视图、卡片等）。
ha_save_dashboard	保存或替换仪表盘配置（需要 HA_ALLOW_CONFIG_WRITE）。
ha_create_dashboard	注册新的存储模式仪表盘（需要 HA_ALLOW_CONFIG_WRITE）。
ha_delete_dashboard	按 ID 删除仪表盘（需要 HA_ALLOW_CONFIG_WRITE）。

仪表盘使用 Home Assistant 的 WebSocket API。在代理模式下，VomeHome 通过 POST /api/v1/instances/<id>/ha/ws/command 代理允许列表中的部分命令。 | ha_fire_event | 在事件总线上触发自定义事件。 |

ESPHome（通过中继连接到 HA）

工具	描述
esphome_dashboard_info	说明如何访问 ESPHome，以及当前是否可刷写和查看日志。
esphome_list_devices	列出仪表盘配置／设备；标记需要重命名的配置。
esphome_list_migrations	列出配置仍在使用、但已重命名的 ESPHome 拼写形式。
esphome_get_config	读取配置的 YAML。
esphome_save_config	完整写入配置的 YAML，用于创建新文件（写入受控）。
esphome_edit_config	通过精确查找和替换就地更改配置的部分内容，无需重新发送长文件（写入受控）。
vome_health_report	Vome 对家庭的健康评分和每项发现，包含严重程度、证据、建议及涉及的实体。
vome_health_check	运行新的健康检查，以便在修复后重新评分（写入受控）。
esphome_validate	验证配置。
esphome_compile	编译固件。
esphome_upload	编译并通过无线方式刷写设备；先进行验证（写入受控）。
esphome_logs	读取设备的实时日志——启动、Wi-Fi、传感器、崩溃信息。
esphome_clean	在因构建缓存过期导致编译失败后，删除缓存的构建文件（写入受控）。

**无需进行任何配置。**所有命令——包括构建和日志——都通过 VomeHome 中继，因此只要 Home Assistant 代理模式可用，ESPHome 就能使用，无需开放端口。

此外，没有其他访问途径。ESPHome 插件使用主机网络，且禁用了 Web 端口；其入口只允许 Supervisor 和 localhost 访问，因此只有家庭网络中的 Vome 组件能够访问仪表盘。过去曾有直接仪表盘模式（ESPHOME_DASHBOARD_URL），但已在 0.6.0 中移除：它使用的协议已被 ESPHome 删除，而且在默认安装中本来也无法连接。

Node-RED（NODERED_URL）

Node-RED 是随 Home Assistant 提供的基于流程的编辑器。它功能强大，但手动编辑很繁琐——因此可以让 Agent 为你读取和写入流程 JSON。流程以 JSON 节点数组的形式存储，并按选项卡分组；这些工具可逐个选项卡（安全）或针对整个配置（需谨慎）操作。写入操作与编辑 HA 自动化一样，受相同开关控制（HA_ALLOW_WRITE + HA_ALLOW_CONFIG_WRITE）。

工具	描述
nodered_get_flows	获取完整的流程配置（所有选项卡）以及当前修订版本。
nodered_get_flow	按 ID 获取一个流程（选项卡）及其节点。
nodered_list_nodes	列出已安装的节点模块／类型（调色板）。
nodered_create_flow	添加新选项卡，不影响现有流程（写入受控）。
nodered_update_flow	按 ID 替换一个选项卡，其他选项卡保持不变（写入受控）。
nodered_delete_flow	删除一个选项卡及其节点（写入受控）。
nodered_set_flows	替换整个流程配置并部署（写入受控）。

VomeHome（需要 VOMEHOME_TOKEN）

VomeHome 是托管式 Home Assistant 服务。使用 GitHub 登录门户，在 Account → API tokens 下创建个人访问令牌，然后 Agent 就可以在编辑器中管理你的实例。高级管理功能仍需在门户中通过完整的浏览器登录使用。

工具	描述
vomehome_list_instances	列出你的 HA 实例及其状态、套餐、URL、实时健康状况、当前活动实例，以及各实例的客户端写入/配置访问权限。
vomehome_get_instance	获取单个实例的详情和实时状态。
vomehome_use_instance	切换 ha_* 工具所操作的实例（多实例使用方式请参阅从一个令牌管理多个实例）。
vomehome_reboot_instance	重启实例的 VM（受写入权限限制）。
vomehome_create_instance	创建临时测试/沙盒实例（API 密钥需要创建权限范围；创建实例的密钥会获得新实例的完整 HA 访问权限，且该实例会成为当前活动目标）。
vomehome_get_login_url	生成一键式 HA 登录 URL，以便在新标签页中打开。
vomehome_list_backups	列出 Home Assistant 的 Vome 备份位置中的备份（需要 ha:files）。
vomehome_backup_download_link	获取单个备份 .tar 文件的下载链接，有效期约 15 分钟（需要 ha:files）。
vomehome_create_guest_link	创建非管理员 HA 用户和一键式登录 URL，以供分享（需要 HA_ALLOW_CONFIG_WRITE）。仅适用于 Vome 托管的实例。
vomehome_list_guest_links	列出实例的访客链接，包括已撤销的链接。
vomehome_revoke_guest_link	立即撤销访客链接。

访客链接支持自助创建、可撤销的分享：按需创建并删除一个非管理员 Home Assistant 账户（除非传入 admin: true）及其一键式登录 URL，无需交出所有者自己的凭据。访客链接仅适用于 Vome 托管的实例——为所有者以外的人创建令牌需要直接访问 VM 的网络，而自托管/通过中继连接的实例无法通过门户提供这种访问。

Home Assistant 的权限模型粒度较粗。 非管理员访客无法访问 Settings 和 Developer Tools，但仍能对其仪表板中显示的任何实体调用服务——Home Assistant 本身不支持按实体限制访客权限。访客链接适用于专门用于体验和试用的演示/沙盒实例。但它不能替代对他人实际住宅的访问控制——切勿将其用于此类场景。链接会自动过期（expires_in，默认 24h，最长 30 days——Home Assistant 自己的长期令牌不会自动过期，因此由 Vome 强制执行），也可以随时提前撤销。

集成与配置条目

工具	描述
ha_list_config_entries	列出已安装的集成（配置条目）。可选的域筛选条件。
ha_delete_config_entry	按 ID 删除配置条目——用于修复移除设备后遗留的孤立/重复条目；否则重新添加的设备实体会带上 _2 后缀。需要 HA_ALLOW_CONFIG_WRITE。
ha_list_discovery_flows	列出 Home Assistant 在网络上发现但尚未添加的集成。
ha_config_flow	启动（handler）、重新配置现有条目（entry_id），或继续（flow_id + user_input）集成的配置流程。需要 HA_ALLOW_CONFIG_WRITE。
ha_config_entry_options	读取或设置集成选项——包括 ESPHome 的 allow_service_calls。
ha_integration_setup_vome	使用默认设置添加 Vome（vomesync）配置条目，并可安全重复执行。

Supervisor / Vome 插件（HAOS / Supervised）

工具	描述
ha_supervisor_api	通过 supervisor/api 调用 Supervisor 端点（商店、插件等）。由于 supervisor/api 无法传递纯文本，读取 …/logs 会通过日志路由提供；插件启动、停止和重启会等待 50 s，而不是 Home Assistant 的 10 s。
ha_addon_install_vome	将 https://github.com/Vortitron/VomeSync 添加到商店，安装 Vome 并启动。

HACS（Home Assistant 社区商店）

工具	描述
ha_hacs_info	HACS 版本、阶段，以及是否有待处理的后台任务。
ha_hacs_list_repositories	列出 HACS 已知的仓库（可按类别筛选）。
ha_hacs_add_repository	使用 owner/repo 和类别添加自定义仓库。由于 HACS 即使添加失败也会确认，因此会通过重新列出仓库来确认。需要 HA_ALLOW_CONFIG_WRITE。
ha_hacs_download_repository	安装（或更新）已跟踪的仓库——此步骤才会实际写入文件。需要 HA_ALLOW_CONFIG_WRITE。
ha_hacs_remove_repository	卸载仓库文件并停止跟踪该仓库。需要 HA_ALLOW_CONFIG_WRITE。

HACS 没有用于管理仓库的 REST API 或服务调用——这些操作通过 HACS 自有的 WebSocket 命令（hacs/*）执行，与上面的 Supervisor 工具相同。添加仓库只会注册仓库；之后调用 ha_hacs_download_repository 进行安装。如果这是新的集成或插件域，还需重启 Home Assistant。

用户

工具	描述
ha_list_users	列出所有用户：ID、姓名、用户名、角色、活跃状态/所有者状态。
ha_create_user	创建用户并指定角色（admin / user / read_only），但暂不设置登录信息。需要 HA_ALLOW_CONFIG_WRITE。
ha_update_user	更改用户的姓名、角色、活跃状态或仅限本地的限制。需要 HA_ALLOW_CONFIG_WRITE。
ha_delete_user	永久删除用户及其登录信息。需要 HA_ALLOW_CONFIG_WRITE。
ha_set_user_credentials	为尚未设置登录信息的用户设置用户名/密码。需要 HA_ALLOW_CONFIG_WRITE。
ha_change_user_password	重置已有登录信息用户的密码。需要 HA_ALLOW_CONFIG_WRITE。
ha_remove_user_credentials	移除登录信息，但不删除用户。需要 HA_ALLOW_CONFIG_WRITE。
ha_provision_service_login	为程序（MQTT 客户端、Zigbee 网桥、ESPHome 设备）创建专属的非管理员登录信息，并将密码直接写入其附加组件选项或密钥文件。密码在此处生成，且绝不会返回。需要 HA_ALLOW_CONFIG_WRITE，密钥文件还需要 ha:files。

这些工具创建的用户和密码，是可长期使用的 Home Assistant 登录信息， 独立于任何 VomeHome API 密钥。 撤销创建它的密钥不会删除该账户——这与此服务中的其他所有操作不同；其他操作都是 通过调用方的密钥执行，并会在密钥被撤销时立即停止。请将授予某个实例 ha:config 的权限视为等同于信任持有者可在该家庭中永久创建账户。ha_create_user 的 role 没有默认值；必须明确选择，而不能让其悄然默认为 admin。

程序的登录信息：ha_provision_service_login。 将设备接入家庭通常会卡在一个步骤：有人想出一个密码，再把它输入两个地方。ha_set_user_credentials 需要调用方自行选择密码，而 Agent 不应该负责这件事。此工具会自行生成密码（128 位），将其写入使用方的附加组件选项（例如 mqtt.user / mqtt.password）和/或密钥文件，并回复密码存放的位置，而不透露密码本身。Mosquitto 附加组件接受 Home Assistant 登录信息，因此一次调用即可接入 MQTT 客户端。此工具会先检查每个目标，再创建任何内容；如果新登录信息无法写入任何位置，就会将其删除；绝不创建管理员账户；默认仅限本地；使用 rotate=true 时，只会重新签发由自身创建的登录信息（用户名称中标记为 (service login)），绝不会操作个人账户。对于 Home Assistant 之外、既没有附加组件选项也没有密钥文件的程序，此工具无法处理。

ha_config_entry_options 可以访问 API 中其他位置都不存在的设置。最常有人询问的是 ESPHome 的 “允许设备执行 Home Assistant 操作”（allow_service_calls）：没有此设置，设备就无法调用 HA 服务。该设置在界面中需要点好几层，因此经常被遗漏。使用 domain=esphome 调用 ha_list_config_entries 获取条目 ID；先只传入 entry_id 调用以读取表单，然后再传入 user_input 调用。提交时会设置表单上的所有字段，因此请将读取到的值一并传回，只修改你打算更改的内容。

需要 Supervised/HAOS 目标（例如通过 vomehome_create_instance 创建的 VomeHome 沙盒，或 ha-plc-sandbox MCP 条目）。在代理模式下，由 API 密钥的作用域决定权限——不需要 HA_ALLOW_WRITE / VOMEHOME_ALLOW_CREATE 环境标记。仅容器模式的 HA 没有附加组件商店——请在该环境中使用 HACS 安装集成。

典型开发流程：vomehome_create_instance → 等待实例运行 → ha_addon_install_vome → 重启 Core → 添加 Vome 集成。

---

安装

需要 Node.js ≥ 20。无需手动安装任何内容——编辑器会按需通过 npx 启动服务，因此相同的配置可在每台机器上使用（无需绝对路径）。

一键安装（Cursor）

点击按钮，然后编辑预填的 HA_URL 和 HA_TOKEN。（如果点击按钮没有反应，请将本节源代码中的 cursor:// 链接复制到浏览器地址栏。）

单行配置

将以下内容添加到 ~/.cursor/mcp.json（适用于所有项目）或 .cursor/mcp.json（适用于单个项目），并填入你的令牌，即可完成安装：

{
	"mcpServers": {
		"home-assistant": {
			"command": "npx",
			"args": ["-y", "@vortitron/home-assistant-mcp"],
			"env": {
				"HA_URL": "http://homeassistant.local:8123",
				"HA_TOKEN": "paste-your-long-lived-token",
				"HA_ALLOW_WRITE": "false"
			}
		}
	}
}

验证 / 从源码安装

npx -y @vortitron/home-assistant-mcp doctor   # one-off connectivity check

# or hack on it:
git clone https://github.com/Vortitron/home-assistant-mcp.git
cd home-assistant-mcp && npm install && npm run build

局域网 TCP 隧道（RDP 等）

npx -y @vortitron/home-assistant-mcp tunnel --token <jwt> --local-port 3390

在 127.0.0.1:<local-port> 上打开本地侦听器，并通过 Vome 已在使用的同一出站中继将流量转发到与 Vome 关联的 Home Assistant 上的 tcp 方案局域网路由（无需在路由器上设置端口转发），例如 RDP 主机。将 mstsc/Remmina/任意 TCP 客户端指向该本地地址。从 Home Assistant 获取令牌：开发者工具 → 操作 → vomesync.mint_lan_tcp_token（或 Vome App 的接入面板 → 局域网隧道 →“获取隧道令牌”）。令牌有效期较短，且仅适用于一个实例和一条路由。

---

配置

通过环境变量配置（也会读取本地 .env）。将 .env.example 复制为 .env 并填写，或在编辑器的 MCP 配置中设置变量。

变量	默认值	说明
HA_URL	—（必需）	基础 URL，例如 http://homeassistant.local:8123。
HA_TOKEN	—（必需）	长期访问令牌（个人资料 → 安全）。
HA_ALLOW_WRITE	关闭（直连）/ 宽松（经代理）	本地写入保护。在经代理模式下，由 API 密钥的每实例作用域决定（由服务端强制执行）；设置为 false 只会增加本地限制。在直连模式下，这是总开关，默认关闭。
HA_DENY_DOMAINS	lock,alarm_control_panel,cover,valve,camera（直连）/ 空（经代理）	禁止写入的域。在经代理模式下，由 API 密钥的 敏感设备 设置在服务端决定；仅在需要增加本地限制时设置此项。
HA_ALLOW_DOMAINS	(任意)	如果设置，则只能写入这些域。
HA_ALLOW_CONFIG_WRITE	关闭（直连）/ 宽松（经代理）	编辑自动化配置的本地保护。与 HA_ALLOW_WRITE 语义相同。
NODERED_URL	(已禁用)	Node-RED 编辑器/管理后台基础 URL，例如 http://homeassistant.local:1880。启用 nodered_* 工具。
NODERED_TOKEN	—	如果启用了 Node-RED adminAuth，则填写承载令牌。
NODERED_USERNAME / NODERED_PASSWORD	—	如果不想手动创建令牌，可通过 /auth/token 交换获取令牌的凭据。
VOMEHOME_API_URL	https://vome.io	VomeHome 门户基础 URL。
VOMEHOME_TOKEN	(已禁用)	VomeHome 个人访问令牌；启用 vomehome_* 工具。
VOMEHOME_INSTANCE_ID	(直连模式)	用于代理 HA 调用的活动/默认实例。提供令牌且未设置 HA_TOKEN 时，HA 工具会通过 VomeHome 路由（参见经代理模式：真正的边界）。令牌的每实例作用域由门户决定其可执行的操作（由服务端强制执行）。
VOMEHOME_INSTANCES	(无)	可选的 JSON 注册表，用于在启动时登记多个实例，例如 [{"id":"rly-house","label":"home"},{"id":"sbx"}]。此处的每实例 write/config 是可选的本地限制（省略则交由服务端决定）。使用 vomehome_use_instance 在它们之间切换。参见使用一个令牌管理多个实例。
VOMEHOME_ALLOW_CREATE	(遵循密钥设置)	创建实例的可选本地保护。实际权限由 API 密钥的账户级创建作用域决定；设置为 false 可始终在本地阻止创建。你创建的实例会获得该密钥的完整 HA 访问权限，并成为当前会话的活动目标。
HA_TIMEOUT_MS	15000	HTTP/WebSocket 请求超时时间。
MAX_RESULTS	500	列表工具在截断前返回的最大项目数。
LOG_LEVEL	info	error | warn | info | debug（日志输出到 stderr）。

获取令牌

在 Home Assistant 中：点击用户头像（左下角）→ 安全选项卡 → 长期访问令牌 → 创建令牌。

---

编辑器设置

这是一个标准的 stdio MCP 服务，因此同一二进制文件可在任何地方运行。

Cursor

使用上方的一键按钮，或在项目中创建 .cursor/mcp.json（或为所有项目创建 ~/.cursor/mcp.json）。参见 examples/cursor.mcp.json：

{
	"mcpServers": {
		"home-assistant": {
			"command": "npx",
			"args": ["-y", "@vortitron/home-assistant-mcp"],
			"env": {
				"HA_URL": "http://homeassistant.local:8123",
				"HA_TOKEN": "paste-your-long-lived-token",
				"HA_ALLOW_WRITE": "false"
			}
		}
	}
}

VS Code

创建 .vscode/mcp.json（参见 examples/vscode.mcp.json）。 VS Code 可以提示输入令牌，而不将其存储在文件中：

{
	"inputs": [
		{ "id": "ha_token", "type": "promptString", "description": "Home Assistant token", "password": true }
	],
	"servers": {
		"home-assistant": {
			"type": "stdio",
			"command": "npx",
			"args": ["-y", "@vortitron/home-assistant-mcp"],
			"env": {
				"HA_URL": "http://homeassistant.local:8123",
				"HA_TOKEN": "${input:ha_token}"
			}
		}
	}
}

Claude Desktop

在 claude_desktop_config.json 的 mcpServers 下添加相同的代码块。

Claude Code：侧边窗格

Claude Code 使用 .mcp.json 中相同的配置块，也可以一次添加一个服务，使用 claude mcp add-json <name> '<entry>'。通过 Vome，只需运行两条命令，并使用 Vome 应用中 Agent 选项卡里的密钥：

/plugin install vome-connect --marketplace Vortitron/home-assistant-mcp
/plugin install vome-panes --marketplace Vortitron/home-assistant-mcp

第一条命令连接你的家庭（会提示输入密钥），第二条命令安装全部四个窗格。也可以逐个安装：

vome-automation 窗格会显示 Claude 正在处理的自动化、保存后有哪些变化，以及最近一次运行经过了哪些步骤：

/plugin install vome-automation --marketplace Vortitron/home-assistant-mcp

这需要 Claude Code 2.1.275 或更高版本；其 README 介绍了旧版本的两条命令安装方式、如何启用更新，以及在自动模式下应允许使用的只读工具。

查看家庭健康状况时，vome-health 会显示 Vome 的评分和检查结果；Claude 修复问题时会标记进度，之后还会重新评分，并配上掷骰子和烟花效果：

/plugin install vome-health --marketplace Vortitron/home-assistant-mcp

要使用实用的仪表板，vome-dash 会在窗格中显示你的一个仪表板：实时状态、开关和调光控制、半幅摄像头，以及 Claude 修改的卡片高亮显示：

/plugin install vome-dash --marketplace Vortitron/home-assistant-mcp

对于 ESPHome，vome-esphome 会添加一个窗格，其中包含根据 YAML 绘制的设备地图，显示 Claude 正在处理的设备，以及实时显示它执行的构建过程：

/plugin install vome-esphome --marketplace Vortitron/home-assistant-mcp

想找点乐子的话，vome-doom 会在窗格中运行 house.wad：把你的家变成 Doom 关卡，射击灯具就能让它真的熄灭：

/plugin install vome-doom --marketplace Vortitron/home-assistant-mcp

还有一个纯粹为了好玩的小工具，dont-panic 会添加 Guide：一个动态展示 Agent 正在执行的任务，并实时为其撰写不拘一格的 Guide 条目的窗格。其 README 列出了价格等级；/guide canned 不收费：

/plugin install dont-panic --marketplace Vortitron/home-assistant-mcp

如果想通过 Vome 将 Claude Code 连接到家庭，而不使用上述任何配置，请从同一个市场安装 vome-connect；它只需一个密钥。你可以在 Home Assistant 的 Vome 应用 Agent 选项卡中获取密钥，无需注册：

/plugin install vome-connect --marketplace Vortitron/home-assistant-mcp

多个 Home Assistant

mcpServers 下的每个条目都是独立的服务进程，并有自己的环境变量。因此，要控制多个 Home Assistant（每个实例使用不同的令牌），请为每个实例添加一个条目，并为其指定不同的名称。名称会作为前缀添加到编辑器中的工具名称前（例如，ha-home: ha_list_entities），这样 Agent 就始终知道自己正在与哪栋房屋通信。请参阅 examples/cursor.multi.mcp.json：

{
	"mcpServers": {
		"ha-home": {
			"command": "npx",
			"args": ["-y", "@vortitron/home-assistant-mcp"],
			"env": {
				"VOMEHOME_TOKEN": "vh_token-for-home",
				"VOMEHOME_INSTANCE_ID": "rly-aaaaaaaaaaaa"
			}
		},
		"ha-cottage": {
			"command": "npx",
			"args": ["-y", "@vortitron/home-assistant-mcp"],
			"env": {
				"VOMEHOME_TOKEN": "vh_token-for-cottage",
				"VOMEHOME_INSTANCE_ID": "rly-bbbbbbbbbbbb"
			}
		}
	}
}

经代理转发的条目和直连条目可以自由混用（例如，一个经代理转发的家庭实例，加上一个使用 HA_URL/HA_TOKEN 直连的实验室实例），而且每个条目都可以设置各自的安全标志——家庭实例使用只读令牌，测试台则启用写入权限。

使用一个令牌的多个实例

每次调用都指定 Home。 除 vomehome_* 工具外，所有工具都接受可选的 instance_id。如果指定的实例与本次会话当前指向的 Home 不同，调用会被拒绝，而不会从该实例返回结果。写入文件和登录操作本来就要求指定实例，读取操作也需要：重新连接的会话可能会沿用另一个窗口所选的实例；从错误的 Home 返回“未找到实体”或空历史记录，看起来就像是真实结果。

上文的多进程布局是每个令牌对应一个进程。如果多个实例属于同一个 VomeHome 账户（使用同一个令牌），也可以改为使用一个服务，并在运行时切换实例。权限由密钥控制——你可在门户网站上为每个实例授予 ha:write / ha:config 权限，服务会强制执行这些权限——因此，下面的配置只用于指定启动时已知的实例（以及任何可选的本地额外限制）。

{
	"mcpServers": {
		"home-assistant": {
			"command": "npx",
			"args": ["-y", "@vortitron/home-assistant-mcp"],
			"env": {
				"VOMEHOME_TOKEN": "vh_your-account-token",
				"VOMEHOME_INSTANCE_ID": "rly-house",
				"VOMEHOME_INSTANCES": "[{\"id\":\"rly-house\",\"write\":false,\"label\":\"home (locked read-only here)\"},{\"id\":\"sbx-plc\",\"label\":\"PLC sandbox\"}]"
			}
		}
	}
}

• VOMEHOME_INSTANCE_ID 是 ha_* 工具启动时的活动／默认目标实例（会自动作为 "default" 纳入注册表）。该实例可执行的操作由门户网站中令牌按实例设置的权限范围决定。
• VOMEHOME_INSTANCES 用于声明启动时已知的实例。此项可选——令牌本身已能访问这些实例——但它可以固定活动目标，并添加本地限制。此处按实例设置的 write / config 属于可选的仅本地限制：省略则交由服务决定；设为 false 则无论密钥允许什么操作，都让本机上的该实例保持只读（示例会在本地锁定该 Home）。
• vomehome_use_instance 用于切换后续 ha_* 调用所针对的活动实例；vomehome_list_instances 会显示当前活动实例以及各实例的有效访问权限。
• 创建实例（vomehome_create_instance）需要密钥具备创建权限——你拥有自己创建的实例。门户网站会向用于创建实例的密钥授予新实例的完整 Home Assistant 访问权限（ha:read、ha:write、ha:config、ha:files），因此 ha_* 工具无需返回令牌页面即可使用。其他密钥和其他 Home 的设置仍保持你所勾选的状态。该实例也会成为本次会话的活动目标。将其实例 ID 添加到 VOMEHOME_INSTANCES，即可在重启后继续将其列为已知实例。

API 密钥是唯一的事实来源，最终决定权在服务端（如果密钥缺少某项权限范围，它会返回 403）。上面的客户端标志在本机只会进一步限制权限，绝不会扩大令牌可执行的操作范围。

在 Vome 的托管端点上（https://vome.io/mcp，无需安装任何东西），实现相同效果只需一个 URL。会话会从客户端上次切换到的实例开始，且此选择会在服务重启后保留。若要让项目始终从特定 Home 开始，可在 URL 中固定该实例：

{ "mcpServers": { "vome": { "type": "http", "url": "https://vome.io/mcp?instance=rly-house",
	"headers": { "Authorization": "Bearer vh_your-account-token" } } } }

固定实例决定会话的起始位置，不会锁定实例：vomehome_use_instance 仍然可以切换。只有当令牌有权访问该实例时，固定设置才会生效。

验证

npx -y @vortitron/home-assistant-mcp doctor

doctor 会检查 REST、WebSocket 注册表，以及（若已配置）ESPHome 仪表板，并输出健康状况摘要。它不会启动 MCP 服务，因此可以随时运行。

---

安全性

专为安全连接到真实家庭环境而设计：

1. 默认只读（直连模式）。 使用原始 HA_TOKEN 时，MCP 是唯一的防护措施，因此在 HA_ALLOW_WRITE=true 之前，所有更改状态的工具都会拒绝执行。代理模式下，权限则由你的 VomeHome API 密钥控制，并在服务器端按实例实施（请参阅代理模式（真正的边界））。
2. 域名拒绝列表。 即使启用了写入，敏感域名（门锁、警报器、窗帘、阀门、摄像头）仍会被阻止。在直连模式下，将它们从 HA_DENY_DOMAINS 中移除；在代理模式下，在 VomeHome API 令牌页面的敏感设备下为该密钥勾选它们。
3. 可选允许列表。 设置 HA_ALLOW_DOMAINS，仅允许指定的域名。
4. 跨域防护。 ha_call_service 会检查每个目标实体的域名，包括 data 中任意位置嵌套的实体 ID，因此无法通过通用服务（例如 homeassistant.turn_on）访问被拒绝的域名。启用拒绝列表或允许列表时，通用服务若以区域／设备／标签为目标，则会被拒绝，因为这些选择器由服务器端解析，无法在此处检查；请改用目标实体 ID 或域名专用服务（例如 light.turn_on）。
5. 独立的配置写入权限范围。 编辑自动化 YAML 需要单独的 ha:config 权限范围（代理模式），或设置 HA_ALLOW_CONFIG_WRITE=true（直连模式）。
6. VomeHome 防护措施。 重启或创建实例需要 API 密钥具有相应的权限范围（由服务器强制执行）；可选的 VOMEHOME_ALLOW_CREATE 客户端标志还可添加本地拦截。VomeHome 令牌在服务器端限制为只能访问你自己的账户。

工具还带有 MCP 提示标记（readOnlyHint、destructiveHint），以便客户端在执行破坏性调用前发出警告。

写入防护能保护什么（以及不能保护什么）

防护措施会限制这些工具的操作；当 MCP 服务是 Agent 访问 Home Assistant 的唯一途径时，它能提供强有力的保护。它不是加密边界：Home Assistant 长期令牌拥有完整访问权限，因此，如果 Agent同时持有该令牌，就可以直接调用 HA API，绕过防护措施。因此，请将令牌保存在编辑器的 MCP 配置中（最好放在 ~/.cursor/mcp.json 中，并置于 Agent 无法读取的仓库之外），不要放在 Agent 会浏览的文件中。

如需真正的边界，请改用 VomeHome 作为 Agent 的访问入口：它只持有可撤销的 VOMEHOME_TOKEN，而权限强大的 HA 凭据则保留在服务器端，由服务器控制并审计访问，因此 Agent 无法绕过策略。请参阅代理模式（真正的边界）。

---

代理模式（真正的边界）

直连模式很方便，但只有在 Agent也不持有 HA 令牌时，写入防护才有用。代理模式弥补了这一缺口：为 Agent 提供可撤销、受权限范围限制的 VomeHome 令牌和实例 ID，而不提供任何 Home Assistant 令牌。所有 HA 读取／写入操作都会经由 VomeHome 门户代理，该门户会：

• 将 HA 凭据保留在服务器端（Agent 永远无法看到）；
• 按令牌、按实例实施读取／写入／配置权限——对于某个实例，没有 ha:write 权限范围的令牌就确实无法更改该实例，无论如何使用都不行；
• 在服务器端阻止敏感域名（门锁、警报器等），也包括通过通用服务进行的访问（homeassistant.turn_on 无法访问门锁）；
• 针对发起调用的令牌，审计每次调用（无论允许还是拒绝）。

由于策略由服务器端实施，Agent 无法绕过；这就是防护措施与安全边界的区别。

{
	"mcpServers": {
		"home-assistant": {
			"command": "npx",
			"args": ["-y", "@vortitron/home-assistant-mcp"],
			"env": {
				"VOMEHOME_TOKEN": "vh_paste-your-token",
				"VOMEHOME_INSTANCE_ID": "your-instance-id"
			}
		}
	}
}

在门户的 Account → API tokens 中创建令牌。在那里，你可以按实例授予权限，决定令牌是否可以控制 Home Assistant（ha:write）和／或编辑自动化配置（ha:config）；签发密钥后也可以编辑这些授权。密钥是唯一的事实来源；MCP 只负责传递密钥。可从仪表板或 vomehome_list_instances 工具获取实例 ID。（门户的令牌页面会为你生成这段仅含令牌的代码片段。）

vomehome_* 工具的令牌作用域。 实例管理工具（vomehome_list_instances、_get_instance、_use_instance、_get_login_url）需要 instances:read 作用域，而 vomehome_create_instance 需要 instances:write（它也包含读取权限）。仅使用 HA 作用域（ha:read／ha:write／ha:config）创建的令牌可以代理 Home Assistant 调用，但实例工具会返回 403 … missing required scope(s): instances:read。如果你希望 Agent 能启动沙盒，请使用 instances:write 创建令牌。创建实例后，该密钥会自动获得对新实例的完整 ha:* 访问权限（ha:read、ha:write、ha:config、ha:files）——现有家庭仍保留你勾选的授权。在代理模式下不需要本地 VOMEHOME_ALLOW_CREATE 环境变量标志（只有希望在本地阻止创建时才将其设为 false）。 默认（只读）令牌已包含 instances:read——只有在令牌被限定为 HA 访问、却未包含实例作用域时，才会出现 403。

代理模式支持日常操作——列出／获取实体、列出服务、调用服务、读取配置、渲染模板——以及自动化编辑：ha_get_automation、ha_set_automation、ha_delete_automation 和 ha_check_config。Lovelace 仪表板也支持代理操作：ha_list_dashboards、ha_get_dashboard、ha_save_dashboard、ha_create_dashboard、ha_delete_dashboard（写入需要 ha:config）。读取自动化需要 ha:read；写入则需要令牌在该实例上具有单独的 ha:config 作用域，并由服务器端强制执行。在代理模式下，客户端写入保护（HA_ALLOW_WRITE／HA_ALLOW_CONFIG_WRITE）默认允许写入；它们是可选的本地附加限制。注册表工具（区域／设备）、日志和历史记录目前仍需使用直连模式。

通过中继使用 ESPHome。 通过代理连接到已连接中继的 Home Assistant（你自己的 HA 通过 Vome 组件的出站隧道连接）时，ESPHome 也会随之接入——包括列出设备、读取和写入 YAML，以及流式命令（esphome_validate／_compile／_upload／_logs／_clean）；这些命令通过中继以轮询任务的方式运行。读取需要 ha:read；写入 YAML、构建和刷写需要实例的 ha:config 作用域。这是唯一可用的方式：请参阅 ESPHome。

连接你自己的 Home Assistant。 你代理连接的实例不必是 VomeHome VM。在 VomeHome 门户中，Account → Connect HA 可让你连接自己托管的 Home Assistant（公共 URL／外部 IP，或 Nabu Casa Remote UI），并使用长期访问令牌。它随后会以 ext-… ID 出现在 vomehome_list_instances 中——将 VOMEHOME_INSTANCE_ID 设为该 ID，即可使用相同的、带作用域限制、拒绝列表和审计的边界。你的 HA 令牌会保留在 VomeHome 服务器上；Agent 只会接触到可撤销的 VomeHome 令牌。

面向 Agent 的发现信息。 VomeHome 发布了机器可读索引，涵盖以上所有内容——如何注册、创建令牌、启动试用 VM、连接家庭 HA，以及 /api/v1 接口——索引以 Gopher-over-HTTPS 菜单的形式发布在 https://vome.io/.well-known/agent.gopher，并以 llms.txt 格式发布在 https://vome.io/llms.txt。如果你是正在阅读本文的 Agent，请从那里开始。

---

Agent 工作流示例

• “客厅里有哪些灯亮着？” → ha_list_entities（domain light， area living room）。
• “让这个模板仅在日落后返回 true” → 使用 ha_render_template 迭代调整。
• “把门廊灯调到 30%” → ha_call_service（light.turn_on， brightness_pct: 30）。需要启用写入权限。
• “修复我的早晨自动化” → ha_get_automation → 编辑 → ha_set_automation → ha_check_config → ha_trigger_automation。
• “给这个 ESPHome 节点添加一个传感器并刷写它” → esphome_get_config → esphome_edit_config（或使用 esphome_save_config 新建文件）→ esphome_validate → esphome_upload。
• “整理我的 Node-RED ‘Heating’ 标签页” → nodered_get_flows（找到标签页 ID） → nodered_get_flow → 编辑节点 → nodered_update_flow。
• “启动一个沙盒并打开它” → vomehome_create_instance → vomehome_get_instance（轮询状态）→ vomehome_get_login_url（打开链接）。
• “为什么我的 Hue 集成报错？” → ha_get_system_log （logger: "hue"）→ 查看 exception_summary → 再次调用 ha_get_system_log，并设置 include_exception: true 以获取完整堆栈。
• “为什么我的早晨自动化没有运行？” → ha_get_trace （item: "automation.morning"）→ 查看 failed_at。

---

使用日志进行调试

四种日志入口，大致按优先尝试顺序排列：

问题	工具
现在出了什么问题？	ha_get_system_log
为什么这个自动化什么都没做？	ha_get_trace
加载项 / 主机执行了什么操作？	ha_get_supervisor_log
这个实体发生了什么，以及是什么时候？	ha_get_logbook / ha_get_history

先用 ha_get_system_log，而不是 ha_get_error_log。 它会读取 Home Assistant 的结构化错误存储，同一故障即使记录了 500 次，也只会显示为一条记录，其中包含 count: 500、一个 source 文件:行号，以及首次 / 最后出现时间。查看原始日志需要消耗更多 token，得到的信息却更少。默认不包含完整回溯信息——你仍会得到 exception_summary，也就是指出实际异常的最后一行——因此，确定相关条目后，再请求 include_exception: true。

复现循环。 如果你能随时触发问题，就不必翻查历史记录——让日志只包含这次复现：

1. ha_set_log_level（integration: "hue", level: "debug"）——只对一个集成启用调试，而不是全局启用。
2. ha_clear_system_log。
3. 复现问题（ha_call_service、ha_trigger_automation，等等）。
4. ha_get_system_log——返回的所有内容都是由第 3 步引起的。

日志级别仅在运行时生效，重启后会重置。在直连模式下，这两个写入工具都需要 HA_ALLOW_WRITE=true，但不需要 HA_ALLOW_CONFIG_WRITE；域拒绝 / 允许列表不适用——它们更改的是日志处理机制，而不是实体。

轨迹能回答日志无法解答的问题。 条件返回 false 的自动化不会记录任何日志；轨迹会记录它。ha_get_trace 默认返回最近一次运行，并提供 failed_at——第一个出错或求值结果为 false 的步骤——以及触发器和按顺序排列的步骤。Home Assistant 对每个项目只保留少量轨迹（默认 5 条），且不会保留上次重启前的轨迹，因此 ha_list_traces 没有返回内容时，通常意味着“触发它，然后再查看”。

---

ESPHome 注意事项

• REST 端点（/devices、/edit）用于列出和读取／写入 YAML。通过 VomeHome 中继和直接连接时都可使用。
• validate、compile、upload、logs 和 clean 通过仪表板的多路复用 /ws API 运行。通过中继运行时，它们会被代理为任务：门户启动任务后，由此客户端轮询；这样，多分钟的编译即使中间遇到普通 HTTP 超时也能继续。
• Vome 组件负责仪表板协议。 ESPHome 将其仪表板拆分到 esphome-device-builder 中，用单个 /ws 套接字取代了每条命令对应的 WebSocket（/validate、/logs 等）和 /edit REST 端点；上游文档已将其余旧端点标记为弃用。该组件会将 /ws 转换为中继传输的稳定行／退出码流，因此 ESPHome 的改动对这个客户端、门户和中继都是透明的。构建会通过仪表板的任务队列执行，因此由 Agent 触发的构建也会显示在其自己的“固件任务”面板中。
• 需要 0.3.30 或更高版本的 Vome 插件。较旧的组件使用仪表板已不再响应的协议；错误信息会明确说明这一点并指出版本，而不会归咎于 ESPHome。
• 优先使用中继，而不是直接连接仪表板，即使两种方式都可行。直接连接会绕过门户对每个实例执行的范围检查和审计日志——即使令牌已被撤销，只要设备碰巧与 Agent 位于同一网络，仍然可以刷写该设备。此外，这是在默认 HAOS 安装上唯一可行的方式，因为插件的 Web 端口已禁用，且其 ingress 仅允许 Supervisor 和 localhost 访问。
• 发现（src/esphome/discovery.ts）用于直接模式下查找仪表板；此模式没有中继，因此也没有可绕过的策略层。调用 esphome_dashboard_info 可查看当前启用的模式；如果无法连接任何地址，还可查看尝试过的所有地址及各自的失败原因。
• 设置了仪表板密码时，仪表板会使用自己的 Cookie／XSRF 验证 WebSocket 命令，因此这些命令适用于未设置密码的仪表板，或可通过可信网络／终止身份验证的代理访问的仪表板。此处的令牌／基本身份验证仅对后者有帮助。
• esphome_upload 会在刷写前进行验证。设备刷入错误的构建版本后，会一直离线，直到有人用线缆连接它；因此会先执行成本较低的检查。传入 skip_validate: true 可跳过验证。

---

Node-RED 注意事项

• HA Node-RED 插件会在端口 1880 上提供编辑器（http://homeassistant.local:1880）。将 NODERED_URL 指向该地址。
• 如果插件设置了凭据密钥／adminAuth，请提供 NODERED_TOKEN（或 NODERED_USERNAME／NODERED_PASSWORD；客户端会用它们换取令牌）。如果插件只能通过可信网络或 HA ingress／终止身份验证的代理访问，则无需在此处设置身份验证。
• nodered_set_flows 会重写全部内容——日常编辑请优先使用 nodered_create_flow／nodered_update_flow。传入 nodered_get_flows 返回的 rev，这样便能检测到编辑器中的并发更改，而不是静默覆盖。
• Node-RED 工作流是纯 JSON，因此很适合作为其他前端（PLC 风格梯形图、Scratch／Blockly）的目标。这方面的探索记录在 VomeHome 仓库的 docs/alt_interfaces_plan.md 中。

开发

npm run dev          # run from source with tsx (watch)
npm run build        # compile to dist/
npm test             # vitest
npm run lint         # eslint
npm run typecheck    # tsc --noEmit

目录结构：

src/
	index.ts              # entry: MCP stdio server + `doctor`/`tunnel` CLI
	config.ts             # env parsing + validation
	safety.ts             # write-guard policy
	logger.ts             # stderr logger
	ha/                   # Home Assistant REST + WebSocket + brokered clients
	esphome/              # ESPHome dashboard client
	nodered/              # Node-RED admin API client
	vomehome/             # VomeHome portal client
	tools/                # one module per tool group
	cli/doctor.ts         # connectivity check
	cli/tunnel.ts         # raw-TCP LAN tunnel client (RDP, etc.)
tests/                  # vitest unit tests

---

路线图

• 通过 VomeHome 代理 HA 访问（真正的边界）——已交付（MVP）。 HA 读写操作可通过 VomeHome 代理，并使用可撤销的 VOMEHOME_TOKEN， 这样 HA 凭据就不会传到 Agent，同时只读／拒绝域名／审计策略会在服务端强制执行。自动化编辑和 ESPHome REST 子集也通过代理处理（后者通过中继连接的 HA）。参见 代理模式。下一步：通过代理提供注册表（区域／设备）， 并在门户中提供每个令牌的审计视图。
• VomeHome 测试安装。 vomehome_* 工具已可列出、创建、重启 和打开实例。下一步：自动将 HA_URL/HA_TOKEN 指向刚创建的沙盒，让 Agent 在改动真实住宅之前先尝试更改， 然后推广可行的更改。（需要 project_outline.md 中所述的门户 API 端点。）
• 通过中继使用 ESPHome——已交付。 构建、刷写和设备日志通过轮询作业代理，因此远程 Agent 无需暴露入站访问即可刷写硬件， 且每条命令前都会进行范围检查和审计。下一步： 设备接入（/import + 向导流程），让 Agent 无需经过 UI 操作，就能将全新开发板从未刷写状态配置到可用实体。
• Node-RED——流程读取／写入／部署功能已交付。下一步：通过 VomeHome 代理管理 API （与 HA 和 ESPHome REST 子集一样），这样通过中继连接的住宅就不需要可直接访问的 Node-RED URL；并在部署前增加流程 差异对比／验证步骤。
• 用于实体／区域的 MCP 资源（除工具外）。
• 用于远程使用的可选 HTTP/SSE 传输。

---

许可证

MIT © Vortitron