ha-configuration

Home Assistant 配置

何时使用此技能

在以下情况下使用此技能……	在以下情况下改用 ha-automations……
编辑 configuration.yaml	创建自动化规则
设置集成	编写自动化触发条件／操作
管理 secrets.yaml	调试自动化逻辑
使用 packages 进行组织	使用自动化蓝图
排查配置错误	设置设备触发条件

核心配置文件

文件	用途
configuration.yaml	主配置入口
secrets.yaml	敏感值（密码、API 密钥、令牌）
automations.yaml	自动化规则（通常由 UI 管理）
scripts.yaml	可复用脚本序列
scenes.yaml	场景定义
customize.yaml	实体自定义设置
packages/*.yaml	模块化配置包

配置结构

基本 configuration.yaml

homeassistant:
  name: Home
  unit_system: metric
  time_zone: Europe/Helsinki
  currency: EUR
  country: FI

  # External files
  customize: !include customize.yaml
  packages: !include_dir_named packages/

# Core integrations
default_config:

# Text-to-speech
tts:
  - platform: google_translate

automation: !include automations.yaml
script: !include scripts.yaml
scene: !include scenes.yaml

密钥管理

secrets.yaml：

# API keys
openweathermap_api_key: "abc123def456"
spotify_client_id: "your_client_id"
spotify_client_secret: "your_client_secret"

# Database
recorder_db_url: "postgresql://user:pass@localhost/hass"

# MQTT
mqtt_username: "homeassistant"
mqtt_password: "secure_password"

# Network
latitude: 60.1699
longitude: 24.9384

在 configuration.yaml 中引用：

weather:
  - platform: openweathermap
    api_key: !secret openweathermap_api_key

recorder:
  db_url: !secret recorder_db_url

Include 指令

指令	描述	示例
!include	包含单个文件	!include automations.yaml
!include_dir_list	将文件作为列表项包含	!include_dir_list sensors/
!include_dir_named	将文件作为具名映射包含	!include_dir_named packages/
!include_dir_merge_list	将文件合并为单个列表	!include_dir_merge_list automations/
!include_dir_merge_named	将文件合并为单个映射	!include_dir_merge_named integrations/
!secret	引用 secrets.yaml 中的值	!secret api_key
!env_var	环境变量	!env_var DB_PASSWORD

包组织

Packages 可按领域实现模块化配置：

packages/climate.yaml：

climate_package:
  sensor:
    - platform: template
      sensors:
        average_indoor_temp:
          friendly_name: "Average Indoor Temperature"
          unit_of_measurement: "°C"
          value_template: >-
            {{ (states('sensor.living_room_temp') | float +
                states('sensor.bedroom_temp') | float) / 2 | round(1) }}

  automation:
    - alias: "Climate - AC Auto Off"
      trigger:
        - platform: numeric_state
          entity_id: sensor.average_indoor_temp
          below: 22
      action:
        - service: climate.turn_off
          target:
            entity_id: climate.living_room_ac

  script:
    climate_cool_down:
      alias: "Cool Down House"
      sequence:
        - service: climate.set_temperature
          target:
            entity_id: climate.living_room_ac
          data:
            temperature: 20
            hvac_mode: cool

packages/presence.yaml：

presence_package:
  input_boolean:
    guest_mode:
      name: "Guest Mode"
      icon: mdi:account-multiple

  binary_sensor:
    - platform: template
      sensors:
        anyone_home:
          friendly_name: "Anyone Home"
          device_class: presence
          value_template: >-
            {{ is_state('person.user1', 'home') or
               is_state('person.user2', 'home') or
               is_state('input_boolean.guest_mode', 'on') }}

常见集成模式

MQTT 配置

mqtt:
  broker: !secret mqtt_broker
  port: 1883
  username: !secret mqtt_username
  password: !secret mqtt_password
  discovery: true
  discovery_prefix: homeassistant

  sensor:
    - name: "Outdoor Temperature"
      state_topic: "sensors/outdoor/temperature"
      unit_of_measurement: "°C"
      device_class: temperature
      value_template: "{{ value_json.temperature }}"

REST 传感器

sensor:
  - platform: rest
    name: "GitHub Stars"
    resource: https://api.github.com/repos/home-assistant/core
    value_template: "{{ value_json.stargazers_count }}"
    scan_interval: 3600
    headers:
      Authorization: !secret github_token

模板传感器

template:
  - sensor:
      - name: "Sun Elevation"
        unit_of_measurement: "°"
        state: "{{ state_attr('sun.sun', 'elevation') | round(1) }}"

      - name: "Daylight Hours"
        unit_of_measurement: "hours"
        state: >-
          {% set sunrise = as_timestamp(state_attr('sun.sun', 'next_rising')) %}
          {% set sunset = as_timestamp(state_attr('sun.sun', 'next_setting')) %}
          {{ ((sunset - sunrise) / 3600) | round(1) }}

  - binary_sensor:
      - name: "Workday"
        state: "{{ now().weekday() < 5 }}"

输入辅助项

input_boolean:
  vacation_mode:
    name: "Vacation Mode"
    icon: mdi:airplane

input_number:
  target_temperature:
    name: "Target Temperature"
    min: 16
    max: 28
    step: 0.5
    unit_of_measurement: "°C"
    icon: mdi:thermometer

input_select:
  house_mode:
    name: "House Mode"
    options:
      - Home
      - Away
      - Sleep
      - Guest
    icon: mdi:home

input_text:
  notification_message:
    name: "Custom Notification"
    max: 255

input_datetime:
  alarm_time:
    name: "Alarm Time"
    has_date: false
    has_time: true

配置验证

检查配置

# Docker/Container
docker exec homeassistant hass --script check_config

# Home Assistant OS
ha core check

# Supervised
hassio homeassistant check

# Python venv
hass --script check_config -c /path/to/config

常见验证错误

错误	原因	修复方法
found undefined alias	缺少 !secret 值	添加到 secrets.yaml
could not determine a constructor	YAML 语法无效	检查缩进
duplicate key	同一键定义了两次	删除重复项
Platform not found	缺少集成	通过 UI/HACS 安装

Recorder 配置

recorder:
  db_url: !secret recorder_db_url
  purge_keep_days: 10
  commit_interval: 1

  exclude:
    domains:
      - automation
      - updater
    entity_globs:
      - sensor.weather_*
    entities:
      - sun.sun
      - sensor.date

  include:
    domains:
      - sensor
      - binary_sensor
      - switch

Logger 配置

logger:
  default: warning
  logs:
    homeassistant.core: info
    homeassistant.components.mqtt: debug
    custom_components.my_integration: debug
    # Reduce noise
    homeassistant.components.websocket_api: error

Lovelace 仪表盘（YAML 模式）

# configuration.yaml
lovelace:
  mode: yaml
  resources:
    - url: /hacsfiles/button-card/button-card.js
      type: module
  dashboards:
    lovelace-home:
      mode: yaml
      filename: dashboards/home.yaml
      title: Home
      icon: mdi:home
      show_in_sidebar: true

快速参考

YAML 提示

模式	示例
多行字符串	value: >- 或 value: |-
列表项	- item
内联列表	[item1, item2]
注释	# comment
锚点	&anchor_name
引用	*anchor_name
合并	<<: *anchor_name

模板语法

函数	示例
状态值	states('sensor.temp')
状态属性	state_attr('sun.sun', 'elevation')
转换为浮点数	states('sensor.temp') | float
四舍五入	value | round(1)
默认值	states('sensor.x') | default('unknown')
时间戳	as_timestamp(now())
时间差	now() - timedelta(hours=1)

Agent 优化

上下文	命令
验证配置	docker exec homeassistant hass --script check_config 2>&1 | head -50
查找实体用法	grep -r "entity_id:" config/ --include="*.yaml"
查找密钥引用	grep -r "!secret" config/ --include="*.yaml"
列出 packages	ls -la config/packages/
检查 YAML 语法	python3 -c "import yaml; yaml.safe_load(open('file.yaml'))"