Как редактировать configuration.yaml в Home Assistant

Коротко: Большинство настроек Home Assistant делается в интерфейсе, а configuration.yaml нужен только для части интеграций и продвинутых возможностей. Файл лежит в папке /config при Home Assistant OS и в папке, смонтированной в контейнер, при Home Assistant Container. Правят его через File editor, Studio Code Server или Samba. Отступ только пробелами по 2, значения on и off берутся в кавычки, идентификаторы сущностей всегда в нижнем регистре. Большую конфигурацию делят на файлы через !include и пакеты, пароли выносят в secrets.yaml, а правки проверяют и применяют через раздел Tools, вкладка YAML.

Home Assistant устроен так, что владелец дома настраивает его через интерфейс: добавляет устройства, собирает автоматизации, строит дашборды. Файл configuration.yaml нужен не для всего, а для того, что в интерфейс не вынесли: отдельных интеграций, шаблонов, пакетов и других продвинутых возможностей. Если открыть конфигурацию после установки, она окажется короткой, и это нормально.

Ниже порядок действий: где найти файл под свой тип установки, чем его править, что в нём должно остаться, какие три ловушки есть в синтаксисе, как разнести конфигурацию по файлам и как проверить и применить изменения.

Зачем нужен configuration.yaml, если есть интерфейс

Home Assistant позволяет настраивать большинство функций через визуальный интерфейс: так добавляют устройства, включают интеграции и управляют сценариями. Файл configuration.yaml нужен для того, что интерфейсом не настраивается: части интеграций, собственных шаблонов, пакетов и продвинутых параметров. Именно поэтому в свежей установке он короткий, а не большой, как в старых видео и руководствах.

Многие строки, которые раньше писали вручную, сейчас собраны в одной строке default_config: она загружает стандартный набор интеграций. Эту строку не удаляют. Она не отвечает за все интеграции сразу: часть из них, например MQTT, настраивается отдельно, но именно она даёт базовый набор возможностей. Общий разбор старта и первых шагов есть в материале Home Assistant: с чего начать.

Где лежит файл и как к нему добраться

Путь к файлу configuration.yaml зависит от типа установки. При Home Assistant OS файл лежит в папке /config. При Home Assistant Container это папка конфигурации, которую смонтировали в контейнер при запуске: путь задаёт сам пользователь, и по умолчанию его нет.

Точный путь виден в интерфейсе: откройте Settings, затем System, затем Repairs, нажмите меню из трёх точек и выберите System information. В списке будет строка Configuration directory с текущим путём к папке конфигурации. Это быстрее, чем угадывать путь по памяти, особенно в контейнере.

Какой редактор выбрать

При Home Assistant OS проще всего начать с приложения File editor. Откройте приложение, в файловом дереве слева перейдите в папку config и выберите configuration.yaml: файл откроется в простом текстовом редакторе. Альтернатива это Studio Code Server: он даёт подсветку синтаксиса, живую проверку и автодополнение сущностей, но выглядит сложнее и требует больше ресурсов.

Если удобнее править файл на компьютере, поставьте приложение Samba: оно открывает папку конфигурации по сети, и файл можно редактировать в Notepad++ или Visual Studio Code. При Home Assistant Container приложения недоступны, поэтому папку конфигурации подключают тем способом, который выбран при запуске контейнера, а правят файл на хосте.

Что нельзя удалять из файла

Свежий configuration.yaml содержит несколько строк, которые должны остаться на месте. Первая это default_config: она загружает стандартный набор интеграций. Следующие три строки подключают файлы, которыми управляет интерфейс: automation с automations.yaml, script с scripts.yaml и scene с scenes.yaml.

Именно эти include отвечают за автоматизации, скрипты и сцены, созданные мышкой. Если удалить строку, созданные в интерфейсе автоматизации перестанут загружаться, хотя файлы на диске останутся. Если в конфигурацию добавлен блок homeassistant: для настроек или пакетов, вложенные include внутри него тоже остаются на месте. Готовые автоматизации разобраны в статье Home Assistant: 10 автоматизаций, которые стоит настроить.

Синтаксис YAML: отступы, регистр и кавычки

Отступ в YAML задаёт вложенность, и ошибка в нём это самая частая причина, по которой конфигурация не загружается. Использовать нужно ровно 2 пробела на уровень, табуляция запрещена. Если в файл попал таб, Home Assistant сообщит: found character tab that cannot start any token. Верхний ключ пишется без отступа, вложенный с отступом в 2 пробела, элемент списка начинается с дефиса и одного пробела после него.

Home Assistant чувствителен к регистру. Идентификаторы сущностей всегда в нижнем регистре, поэтому binarysensor.FrontDoor не совпадёт с binarysensor.frontdoor. Отдельная ловушка это булевы значения: Y, true, Yes и ON читаются как истина, а n, FALSE, No и off как ложь. Поэтому состояние on обязательно берут в кавычки, как 'on', иначе оно превратится в true. Если один и тот же ключ задан дважды, останется последнее значение, и это тоже источник неожиданного поведения.

Разделение конфигурации через include

Когда файл разрастается, его делят на части тегом !include. Тег ставится там, где YAML ждёт значение, чаще всего как значение верхнего ключа, например script или sensor. Включаемый файл содержит только то, что относится к этому ключу: родительский ключ внутри повторять нельзя, и весь файл заново отступать тоже не нужно.

Например, если в configuration.yaml написано customize с включением customize.yaml, то в самом customize.yaml идут только записи нижнего уровня. Вложенные include работают: включённый файл может включать следующий. Некоторые интеграции поддерживают несколько верхних ключей с разными метками, и тогда части одной интеграции удобно развести по разным файлам, например отдельно автоматизации из интерфейса и отдельно автоматизации, написанные вручную.

Четыре include для целых папок

Для подключения целых папок есть четыре директивы, и они различаются тем, что возвращают и что должно лежать в файлах.

Все четыре директивы сканируют только файлы с расширением .yaml. Файлы с расширением .yml они игнорируют, но такой файл можно подключить напрямую через !include. Директивы работают рекурсивно, то есть обходят и подпапки.

Пакеты: одна функция в одном файле

Пакеты позволяют собрать всю конфигурацию одной функции или одной комнаты в отдельный файл. Описываются они под ключом homeassistant в разделе packages, а имя пакета пишется строчными буквами без пробелов и раскрывается как словарь. Пакет можно задать прямо в configuration.yaml или подключить через !include.

Удобный вариант для папки: homeassistant с packages и директивой !includedirnamed packages. Тогда имя файла становится именем пакета, а имена файлов должны быть уникальны даже в разных подпапках. Есть правило слияния: ключи, которые задают идентификаторы сущностей, нельзя повторять между пакетами и основным файлом. И одно исключение: auth_providers обязан оставаться прямо в configuration.yaml, потому что обрабатывается раньше пакетов.

Секреты: пароли отдельно от конфигурации

configuration.yaml это обычный текстовый файл, и его прочитает любой, у кого есть доступ к файлам. Пароли, токены и ключи API в нём хранить неудобно и небезопасно. Для этого есть отдельный файл secrets.yaml и тег !secret: в конфигурации остаётся ссылка по идентификатору, а значение лежит в secrets.yaml.

Отдельно стоит сказать: secrets.yaml не шифрует данные, он только разделяет их с основной конфигурацией. При разбиении конфигурации секрет ищется сначала в secrets.yaml рядом с файлом, который на него ссылается, затем в родительских папках, и поиск останавливается на папке с главным configuration.yaml. Есть и ограничение: в интерфейсном редакторе автоматизаций и скриптов !secret не поддерживается. Если он использован в automations.yaml или scripts.yaml, перестанут открываться на просмотр все YAML автоматизации и скрипты, поэтому такие файлы выносят отдельно через отдельный ключ automation.

Проверка и применение изменений

Проверка конфигурации запускается автоматически при перезагрузке и при рестарте. Вручную её включают в разделе Settings, затем Tools, вкладка YAML: там есть кнопки проверки конфигурации и перезагрузки. Полная перезагрузка не всегда нужна.

Большинство интеграций, которые не работают с устройствами напрямую, подхватывают изменения без полного рестарта. Если нужная интеграция в списке вкладки YAML есть, выбирайте её и перезагружайте только её. Если её там нет, остаётся полный Restart, и он прерывает автоматизации и скрипты. Перед рестартом полезно убедиться, что свежая резервная копия на месте: как это устроено, разобрано в статье Home Assistant: обновления, резервные копии и восстановление.

Частые вопросы

Обязательно ли перезагружать Home Assistant после правки configuration.yaml?

Не всегда. Большинство интеграций, которые не общаются с устройствами напрямую, применяют правки после перезагрузки на вкладке YAML, а Quick reload перезагружает всю конфигурацию. Полный Restart нужен, когда интеграции нет в списке перезагрузки, и он прерывает автоматизации и скрипты.

Что делать, если файл не загружается из-за отступов?

Проверьте, что вложенность задана пробелами и что на каждом уровне ровно 2 пробела. Табуляция запрещена и даёт ошибку found character tab that cannot start any token. Удобнее править в редакторе, который показывает невидимые символы, например в Studio Code Server.

Можно ли править файл с компьютера по сети?

Да, если установлено приложение Samba: оно открывает папку конфигурации по сети, и файл можно править в Notepad++ или Visual Studio Code. При Home Assistant OS также работают File editor и Studio Code Server прямо в интерфейсе. Перед правкой стоит сделать резервную копию.

Куда положить пароль, чтобы не хранить его в configuration.yaml?

В файл secrets.yaml рядом с конфигурацией, а в configuration.yaml поставить ссылку через тег !secret с идентификатором. Этот файл не шифрует данные, он только убирает пароли и токены из основного файла, поэтому доступ к нему нужно ограничивать и включать его в резервные копии.