进阶 www.home-assistant.io 2026-11-16 12:36:09 · 17 阅读

第1章 用 YAML 编写 Home Assistant 自动化

第 1 章:使用 YAML 编写自动化

Home Assistant 中的自动化通常通过界面创建,但存储为 YAML。YAML 是一种人类可读的数据序列化语言,用于以结构化格式存储和传输数据。在 Home Assistant 中,YAML 常用于配置文件,例如 configuration.yaml 或 automations.yaml。[了解更多]。若要编辑自动化的 YAML,请选择该自动化,点击右上角的菜单按钮,然后选择“在 YAML 中编辑”。

界面会将自动化写入 automations.yaml。该文件由界面管理,请勿手动编辑。

你也可以在 configuration.yaml 或其他 YAML 文件中直接编写自动化。configuration.yaml 是 Home Assistant 的主配置文件,列出了要加载的集成及其配置。某些情况下需手动编辑该文件,但大多数集成可通过界面配置。[了解更多]。要在 configuration.yaml 中添加带标签的自动化块,示例如下: # UI 运行所需的配置 automation: !include automations.yaml

# 带标签的自动化块 automation kitchen: - triggers: - trigger: ...

你可以添加任意数量的带标签自动化块。

修改 YAML 文件中的自动化后,请重新加载它们。具体步骤参见“重新加载自动化”。

配置变量

找不到你的配置文件?

alias 字符串 (可选)

自动化的名称。

id 字符串 (可选)

自动化的唯一 ID。有了 ID,你可以在界面中更改名称和实体 ID,自动化还会存储调试跟踪记录。ID 必须是文本。若需使用数字,请将其放在引号中,例如 id: "1700000000000"。

description 字符串 (可选)

自动化的描述。

initial_state 布尔值 (可选)

用于定义自动化启动时的状态。若未设置,状态将从上次运行中恢复。若无可恢复的状态,则自动化默认开启。参见“自动化初始状态”。

默认值:从上次运行恢复,否则为 true

trace 映射 (可选,默认:{})

用于配置存储的跟踪记录,目前仅可配置 stored_traces。

stored_traces 整数 (可选,默认:5)

要存储的跟踪记录数量。参见“存储的调试跟踪记录数量”。

variables 映射 (可选,默认:{})

在条件和操作模板中可用的变量。

参数名 任意值

变量的值。任意有效的 YAML 均可。也可使用模板为变量传值。

trigger_variables 映射 (可选,默认:{})

可在所有触发器模板中使用的变量,例如在模板触发器、触发器的 enabled 选项、事件触发器的 event_type、Webhook 触发器的 webhook_id 或 MQTT 触发器的 topic 中。Home Assistant 在设置触发器时(如加载自动化或开启自动化时)会设置这些变量。

参数名 任意值

变量的值。任意有效的 YAML 均可。仅支持受限模板。

mode 字符串 (可选,默认:single)

控制当自动化仍在执行时再次被调用会发生什么。参见“自动化模式”。

max 整数 (可选,默认:10)

控制同时执行和/或排队的最大运行次数。仅适用于 queued 和 parallel 模式。最小值为 2。

max_exceeded 字符串 (可选,默认:warning)

当超过 max 值时(在 single 模式下实际为 1),会输出日志消息。此选项控制该日志消息的严重级别。参见“日志级别”获取有效选项列表。也可设置为 silent 以抑制消息输出。

triggers 列表 必需

启动自动化的触发器。可添加多个触发器,当其中任何一个触发时,自动化即启动。

alias 字符串 (可选)

触发器的名称。显示在自动化编辑器和跟踪记录中。

id 字符串 (可选)

用于在自动化中确定是哪个触发器启动了自动化的 ID。ID 必须是文本。若需使用数字,请将其放在引号中。

enabled 布尔值 | 模板 (可选,默认:true)

设置为 false 可禁用触发器。也可使用受限模板。详情参见“禁用触发器”。

variables 映射 (可选,默认:{})

在条件和操作序列中可用的变量。

参数名 任意值

变量的值。任意有效的 YAML 均可。也可使用模板为变量传值。

conditions 列表 (可选)

自动化执行操作前必须为真的条件。当触发器启动自动化时,Home Assistant 会检查条件。若条件不满足,自动化将停止。默认情况下,列出的所有条件都必须为真。要更改此行为,请使用 And、Or 和 Not 条件。

actions 列表 必需

自动化中要执行的操作序列。

YAML 示例

一个基于 YAML 的自动化示例,可添加到 configuration.yaml。 # configuration.yaml 中的条目示例 automation my_lights: # 日落前 1 小时若有人在家则开灯 # 若有人在 16:00-23:00 之间到家则开灯 - alias: "规则 1 晚间开灯" triggers: # 每个触发器配置的第一行前加 '-' 以输入多个 - trigger: sun event: sunset offset: "-01:00:00" - trigger: state entity_id: - person.paulus - person.anne_therese to: "home" conditions: # 每个条件配置的第一行前加 '-' 以输入多个 - condition: state entity_id: - person.paulus - person.anne_therese match: any state: "home" - condition: time after: "16:00:00" before: "23:00:00" actions: # 单个操作项前无需 '-',但也可以加 - action: homeassistant.turn_on target: entity_id: light.living_room

# 所有人离开家时关灯 - alias: "规则 2 - 离家模式" triggers: - trigger: state entity_id: zone.home to: "0" actions: - action: light.turn_off target: entity_id: all

# 晚上 Paulus 离家时发送通知 - alias: "离家通知" triggers: - trigger: zone event: leave zone: zone.home entity_id: device_tracker.paulus conditions: - condition: time after: "20:00" actions: - action: notify.notify data: message: "Paulus 离开了家"

# 通过 Pushover 发送小米魔方的事件通知。小米集成自定义事件。 - alias: "小米魔方操作" initial_state: false triggers: - trigger: event event_type: cube_action event_data: entity_id: binary_sensor.cube_158d000103a3de actions: - action: notify.pushover data: title: "检测到魔方事件" message: "魔方触发了此事件:{{ trigger.event }}"

旧版 YAML 语法

旧示例(如论坛帖子、指南或蓝图)可能使用了已更名的键。Home Assistant 仍接受旧键,因此这些示例保持可用。在编辑器中保存自动化时,Home Assistant 会将键更改为当前名称。

已更名的键包括:

操作中的 service: 现更名为 action:。

在 Home Assistant 2024.8 中更名。

触发器中的 platform: 现更名为 trigger:。

在 Home Assistant 2024.10 中更名。

自动化的顶层 trigger:、condition: 和 action: 键现更名为 triggers:、conditions: 和 actions:。

在 Home Assistant 2024.10 中更名。

在自动化级别,triggers:、conditions: 和 actions: 为复数。在这些列表中识别触发器或条件的键保持单数(trigger: 或 condition:),而操作调用使用单数 action:。

在同一位置使用旧键或新键,不可混用。例如,自动化不能同时包含 trigger: 和 triggers:。在将旧示例的部分内容复制到自动化之前,请将其键更改为当前名称。

额外选项

某些选项仅在直接通过 YAML 编写自动化时可用,无法通过用户界面配置。

自动化初始状态

启动时,自动化默认恢复 Home Assistant 运行结束时的最后状态。这可由 initial_state 选项控制。设为 false 或 true 可强制初始状态为关或开。 automation: - alias: "自动化名称" initial_state: false triggers: - trigger: ...

存储的调试跟踪记录数量

使用 YAML 时,你可以配置自动化存储的调试跟踪记录数量。这由 trace 下的 stored_traces 选项控制。将 stored_traces 设置为你希望存储的跟踪记录数量。若未指定,默认值为 5。 automation: - alias: "自动化名称" trace: stored_traces: 10 triggers: - trigger: ...

将 YAML 自动化迁移到 automations.yaml

若要迁移手动编写的自动化以使用编辑器,需将其复制到 automations.yaml。确保 automations.yaml 保持为列表!每复制一个自动化,都必须添加一个 id。只要是唯一的字符串即可。 # automations.yaml 条目示例。注意,automations.yaml 始终是列表! - id: my_unique_id # <-- 编辑器运行必需,使用编辑器创建的自动化会自动生成 id alias: "Hello world" triggers: - trigger: state entity_id: sun.sun from: below_horizon to: above_horizon conditions: - condition: numeric_state entity_id: sensor.temperature above: 17 below: 25 value_template: "{{ float(state.state) + 2 }}" actions: - action: light.turn_on

从 YAML 文件中删除自动化

若要删除在界面中管理的自动化,请使用自动化编辑器。步骤参见“复制、关闭或删除自动化”。

删除自动化前,请检查是否有其他自动化、脚本或仪表盘使用了它。

要删除通过 YAML 编写的自动化:

打开包含该自动化的 YAML 文件,例如 configuration.yaml。关于如何设置文件访问和编辑器,参见“编辑 configuration.yaml”。

若自动化在 automations.yaml 中且有 id,请在自动化编辑器中删除。

删除整个自动化。它始于以 - 开头的行,例如 - id:、- alias: 或 - triggers:。止于下一个相同缩进且以 - 开头的行之前。

若使用 !include_dir_list 将自动化拆分为每个文件一个自动化,则文件仅包含此自动化,且开头无 -。请删除整个文件。

检查配置,然后重新加载自动化。

结果:自动化被移除。若其曾有 id,实体将保留,直到你删除它。

若自动化曾有 id,请删除其实体:

前往 设置 > 设备与服务 > 实体。 选择 进入选择模式,然后选择该自动化。 选择三点菜单,然后选择 删除所选。确认删除。

重新加载自动化

修改 YAML 文件中的自动化后,重新加载以应用更改。重新加载仅影响你修改的自动化:

若其中一个正在运行,该运行将停止。 若其中一个有正在进行的“至少持续”时间,该持续时间将丢失。

详情参见“运行未完成时停止的情况”。

前往 设置 > 工具 > YAML。 在 YAML 配置重新加载下,选择 自动化。

若要在自动化或脚本中重新加载自动化,请使用 重新加载自动化 操作。

帮助我们改进文档

此页面对你有帮助吗?

建议编辑此页面,或查看/提供此页面的反馈。

编辑 提供反馈 查看已提供的反馈

评论 (0)