ha-configuration

Home Assistant の設定

このスキルを使用する場面

次の場合はこのスキルを使用します…	次の場合は ha-automations を使用します…
configuration.yaml を編集する場合	自動化ルールを作成する場合
インテグレーションを設定する場合	自動化のトリガー／アクションを記述する場合
secrets.yaml を管理する場合	自動化ロジックをデバッグする場合
パッケージで整理する場合	自動化のブループリントを扱う場合
設定エラーをトラブルシューティングする場合	デバイストリガーを設定する場合

主な設定ファイル

ファイル	用途
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 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/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	同じキーが 2 回定義されている	重複を削除する
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)

エージェント向け最適化

コンテキスト	コマンド
設定を検証する	docker exec homeassistant hass --script check_config 2>&1 | head -50
エンティティの使用箇所を検索する	grep -r "entity_id:" config/ --include="*.yaml"
シークレット参照を検索する	grep -r "!secret" config/ --include="*.yaml"
パッケージを一覧表示する	ls -la config/packages/
YAML 構文を確認する	python3 -c "import yaml; yaml.safe_load(open('file.yaml'))"