Home Assistant 恒温器运行模式设置：`nexia.set_hvac_run

Home Assistant 恒温器运行模式设置：`nexia.set_hvac_run_mode`动作完整指南

【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io

导读

nexia.set_hvac_run_mode是 Home Assistant 中 Nexia/American Standard/Trane 恒温器集成提供的核心动作，用于一键设置温控器的**运行模式（run mode）**与HVAC 模式（hvac mode）——即决定温控器是遵循既定日程（schedule）还是锁定当前设定（hold），以及具体执行制热（heat）、制冷（cool）还是自动（auto）。阅读本文后，你将掌握如何在自动化与脚本中以可视化 UI 或纯 YAML 两种方式调用该动作，理解其参数语义、目标定位（targeting）机制与调用限制，并知晓它在本仓库文档体系中的实现与佐证位置。

一、动作概览：run mode 与 HVAC mode 分别控制什么

该动作的官方定位（见动作文档的 frontmatter）是：

Sets the run mode and HVAC mode on a Nexia thermostat.

它适用于Nexia、American Standard、Trane三个品牌系的恒温器。动作一次调用可以只设置运行模式、只设置 HVAC 模式，或两者同时设置，两个参数在语义上互不干扰：

参数维度	控制的内容	可选值
Run mode（运行模式）	温控器是遵循内置日程，还是锁定当前设定值	`permanent_hold`（永久锁定当前设定）、`run_schedule`（遵循日程）
HVAC mode（暖通模式）	温控器执行制热、制冷还是自动切换	`auto`、`cool`、`heat`

Run mode 决定"要不要跟日程"：run_schedule让温控器回到日程表，按预定时间点自动切换目标温度；permanent_hold则绕过日程，永久保持当前设定值，直到再次被切换回日程模式。
HVAC mode 决定"干什么活"：heat只制热、cool只制冷、auto让温控器按需在制热/制冷之间自动切换。

这两个概念与 Nexia 集成的设备能力直接对应。根据 Nexia/American Standard/Trane 集成文档，该集成为每个温控器区（zone）提供Hold mode（保持模式）开关——开启即对应 permanent hold，关闭即恢复遵循日程；同时为支持紧急加热的设备提供Emergency heat（紧急加热）开关。本动作相当于用程序化的方式，把这类"保持/日程"与"制热/制冷"操作合并到一个原子调用中。

二、在 UI 中使用该动作：自动化与脚本的可视化配置

如果你习惯可视化构建自动化，Home Assistant 会在界面上逐步引导完成配置（对应通用说明 actions/ui_header.md），无需任何 YAML 知识。官方步骤如下：

进入Settings（设置） >Automations & scenes（自动化与场景）。
打开现有的自动化或脚本；若没有，选择Create automation>Create new automation（创建自动化 > 创建新自动化）。
若是新建自动化，在When（当……时）区域添加一个触发条件。脚本不需要触发条件——它们由其他内容在需要时调用。
在Then do（然后执行）区域，选择Add action（添加动作）。
选择你要控制的对象。在By target（按目标，详见下文"目标定位"）下，选择要控制的温控器。
在针对该目标展示的动作列表中，选择Nexia: Set HVAC run mode（Nexia：设置 HVAC 运行模式）。
设置Run mode、HVAC mode，或两者都设置。
点击Save（保存）。

UI 中的选项字段

在可视化界面中，动作暴露两个可选字段（由 options_ui 插件渲染为表单）：

字段	是否必填	说明
Run mode	否	温控器如何遵循日程：`permanent_hold`表示保持当前设定，`run_schedule`表示遵循日程。
HVAC mode	否	要设置的 HVAC 模式：`auto`、`cool`或`heat`。

三、在 YAML 中使用该动作：完整配置示例

如果你直接编写 YAML，或希望精确了解 Home Assistant 在底层执行了什么（对应通用说明 actions/yaml_header.md），请按以下技术参考配置。动作在 YAML 中引用名称为nexia.set_hvac_run_mode。

基础示例（官方示例，见动作文档的{% example %}块）：

action: nexia.set_hvac_run_mode target: entity_id: climate.downstairs data: run_mode: permanent_hold hvac_mode: cool

该示例的效果是：将climate.downstairs锁定在制冷模式（permanent hold + cool）。结合上文概念可理解为——先让温控器进入"保持当前设定"的状态，再把 HVAC 模式设为制冷，两步合并在一次动作调用中完成。

YAML 字段参考表

YAML 字段与 UI 字段一一对应（由 options_yaml 插件渲染为标准配置变量表，含类型标注与必填徽章）：

字段	类型	必填	说明
`run_mode`	string	否	温控器如何遵循日程：`permanent_hold`表示保持当前设定，`run_schedule`表示遵循日程。
`hvac_mode`	string	否	要设置的 HVAC 模式：`auto`、`cool`或`heat`。

目标定位（Targets）

该动作必须指定目标（target）。目标即动作的作用对象，你可以将动作指向单个实体、设备、区域、楼层或标签，Home Assistant 会对目标背后所有匹配的climate实体执行该动作（通用说明 actions/targets.md）：

Entity（实体）：一个具体的climate实体，例如climate.downstairs。
Device（设备）：属于某设备的所有climate实体。
Area（区域）：某个房间/区域内的所有climate实体。
Floor（楼层）：某个楼层上的所有climate实体。
Label（标签）：共享某一标签的所有climate实体。

你还可以在同一动作中混合不同目标类型，例如同时添加一个具体实体和一个区域作为目标，一次调用同时作用于两者。由于动作的 domain 是climate，只有类型为climate的实体（即本集成暴露的温控器实体）才会被命中。

四、注意事项：参数组合约束

官方在Good to know一节明确了一个重要的调用约束：

两个选项都是可选的，但Run mode与HVAC mode至少必须提供其中一个。

也就是说：

只传run_mode合法（例如仅把温控器切回日程模式，不改变制热/制冷设置）；
只传hvac_mode合法（例如仅切换到制冷，不改变日程/保持状态）；
两者都传合法（即前文示例的"保持 + 制冷"组合）；
两者都不传非法——空调用没有任何意义，会被拒绝。

五、快速试验：开发者工具中的 Actions

想在写自动化之前先验证动作效果？打开Settings（设置） >Tools（工具） >Actions（动作），搜索nexia.set_hvac_run_mode，填入字段后点击Perform action（执行动作）（通用说明 actions/try_it.md）。你可以在不写一行 YAML 的情况下，在真实实体上立即看到效果，例如观察温控器是否从"遵循日程"切换为"永久保持 + 制冷"。

六、相关动作：同一集成下的兄弟动作

该动作在文档 frontmatter 中声明了三个相关动作（见 nexia.set_hvac_run_mode.markdown 的related_actions字段，由 actions/related.md 渲染为相关动作列表），它们共同构成 Nexia 恒温器的程序化控制能力：

动作	作用
nexia.set_aircleaner_mode	设置 Nexia 恒温器的空气净化器模式。
nexia.set_humidify_setpoint	设置加湿设定点。
nexia.set_dehumidify_setpoint	设置除湿设定点。

配合使用时，你可以在一套自动化中同时管理温控器的运行/HVAC 模式、空气净化与湿度设定。

七、仓库佐证：从源码看文档机制与集成背景

1. 动作文档的渲染机制

本仓库中每份动作文档都通过一组 Liquid 插件与 include 片段来保证 UI 与 YAML 两套说明的一致渲染：

plugins/options_yaml.rb：OptionsYamlBlock继承自ConfigurationBlock，通过SafeYAML.load解析 YAML 选项映射，并复用render_config_vars渲染标准配置变量表（含类型链接与 Required/Optional 徽章）——这正是前文"YAML 字段参考表"在站点上的实际呈现方式。
plugins/options_ui.rb：渲染 UI 表单侧的选项说明，与 options_yaml 保持同一份字段语义。
plugins/example.rb：ExampleBlock支持action输入类型（标签为Action，语言高亮为yaml，图标mdi:play-circle-outline），将文档中的{% example %}代码块转为带语法高亮的可复制示例——即前文的基础 YAML 示例。
通用步骤片段统一存放于 source/_includes/actions/（ui_header.md、yaml_header.md、targets.md、try_it.md、related.md等），确保所有动作页面遵循同一套交互逻辑与术语。

2. 动作背后的集成背景

nexia域对应的是 Nexia/American Standard/Trane 集成：它通过云端轮询（ha_iot_class: Cloud Polling）方式接入 mynexia.com / asairhome.com 的温控器，自 Home Assistant 0.108 起提供，支持climate、sensor、switch、scene、number、binary_sensor等平台，且通过 DHCP 自动发现。文档明确列出的受支持机型包括：

Trane：XL1050、XL850、XL824；
American Standard：AZONE1050、AZONE850、ACONT824；
明确不支持：XL624、XL950、AZONE950、AZEMT500、AZEMT400B；其他机型可能可用但未经测试。

从集成文档可以推断，run_mode: permanent_hold与集成提供的每个温控器区（zone）的Hold mode开关逻辑一致（开启即保持设定，关闭即遵循日程），hvac_mode则直接映射 climate 平台的标准 HVAC 模式。如果你使用的是支持本地直连的机型，还可关注同域的对偶方案 Trane Local 集成（通过 mTLS 本地控制、状态实时推送，无需云端）；但需注意，nexia.set_hvac_run_mode属于云端 Nexia 集成的动作，其目标实体由 Nexia 集成创建。

八、遇到问题怎么办

若动作未按预期生效，官方建议（见 actions/stuck.md）：

在社区论坛发帖时，附上你正在调用的动作与期望行为，便于他人定位问题；
也可以向 AI 助手用自然语言描述你的诉求，让其推荐或解释合适的动作。

排查时可优先确认：目标实体是否属于 Nexia 集成创建的climate实体、设备机型是否在支持列表内，以及是否至少提供了run_mode与hvac_mode中的一个参数。

【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析