Jede Home-Assistant-Installation startet aufgeräumt. Eine configuration.yaml mit einer Handvoll Zeilen, daneben ein paar Dateien, die das System selbst verwaltet. Zwei Jahre später sieht das bei vielen anders aus: eine Hauptdatei mit 800 Zeilen, in der niemand mehr etwas findet. Das muss nicht sein, und der Weg zur Ordnung ist kürzer als gedacht.
Im Video gehe ich durch mein Konfigurationsverzeichnis und zeige, was wohin gehört. Hier die Struktur zum Nachbauen.
Was im Konfigurationsverzeichnis liegt
Ein frisches Setup bringt schon eine sinnvolle Aufteilung mit. Die wichtigsten Dateien:
| Datei | Inhalt | Wer schreibt rein? |
|---|---|---|
configuration.yaml | Zentrale Konfiguration | Du |
automations.yaml | Alle UI-erstellten Automationen | Der Automations-Editor |
scripts.yaml | Alle UI-erstellten Skripte | Der Skript-Editor |
scenes.yaml | Alle UI-erstellten Szenen | Der Szenen-Editor |
secrets.yaml | Passwörter, Tokens, URLs | Du |
.storage/ | Interne Daten, UI-Einstellungen | Nur Home Assistant |
Zwei Dinge daraus solltest du verinnerlichen. Erstens: In automations.yaml, scripts.yaml und scenes.yaml schreibt der jeweilige Editor. Du kannst dort lesen und auch mal von Hand eingreifen, aber rechne damit, dass die UI die Datei neu formatiert. Zweitens: Der Ordner .storage ist tabu. Dort verwaltet Home Assistant seine internen Daten, Handänderungen können dein Setup zerlegen.
Aus dem ersten Punkt folgt etwas, das vielen nicht klar ist: Du hast für Automationen, Szenen und Skripte immer zwei Bearbeitungswege. Klickst du dir im Frontend eine Szene wie "Bürobeleuchtung einschalten" zusammen, landet sie als YAML in der scenes.yaml. Dort kannst du genauso gut Entitäten austauschen oder Helligkeitswerte anpassen, die Änderung taucht danach wieder in der UI auf. Die grafische Oberfläche ist am Ende nur eine hübsche Darstellung dieser Dateien. Wenn du das einmal verstanden hast, verliert die ganze Konfigurationsgeschichte ihren Schrecken.
Auslagern mit include
Das eigentliche Werkzeug für Ordnung heißt !include. Damit sagst du der configuration.yaml: Der Inhalt dieses Abschnitts liegt in einer eigenen Datei. Genau so bindet Home Assistant ab Werk die Automationen ein, und dasselbe kannst du für deine eigenen Bereiche tun:
1# configuration.yaml
2automation: !include automations.yaml
3script: !include scripts.yaml
4scene: !include scenes.yaml
5
6# Eigene Auslagerungen
7template: !include templates.yaml
8rest: !include rest.yamlWichtig zu verstehen: Die ausgelagerte Datei beginnt direkt mit dem Inhalt, der sonst unter dem Schlüssel stehen würde, eine Einrückungsebene weiter links. Die YAML-Grundlagen dazu hatte ich im letzten Video, der YAML-Guide fasst sie zusammen.
Wer noch weiter gehen will, nutzt !include_dir_merge_list und Verwandte, um ganze Ordner einzubinden. Dann bekommt jede Automation ihre eigene Datei. Für die meisten Setups ist das Overkill, aber ab etwa 50 Automationen wird es interessant.
Warum sich der Aufwand lohnt, zeigt ein Blick in meine eigene automations.yaml: über 2.500 Zeilen YAML. Stell dir vor, das alles stünde zusammen mit Sensoren, Templates und Grundeinstellungen in einer einzigen configuration.yaml. Da blickt kein Mensch mehr durch, und wenn du etwas suchst, wirst du es nicht finden.
Packages: Konfiguration nach Themen bündeln
Includes nach Typ sind ein guter Anfang: alle Sensoren in eine Datei, alle Switches in eine andere. Irgendwann habe ich aber gemerkt, dass mich das nur halb weiterbringt. Wenn ich etwas an meinem Drucker ändern will, ist mir egal, ob das ein Sensor, ein Helfer oder ein Template ist. Ich will alles zum Drucker an einem Ort haben.
Genau das machen Packages. Du legst im Konfigurationsverzeichnis einen Ordner packages an und bindest ihn mit zwei Zeilen ein:
# configuration.yaml
homeassistant:
packages: !include_dir_named packagesAb jetzt liest Home Assistant beim Start automatisch jede Datei aus diesem Ordner ein. Neue Datei reinwerfen, fertig, kein zusätzlicher Eintrag in der configuration.yaml nötig. Bei mir liegen dort Dateien wie tesla.yaml, drucker.yaml oder whirlpool.yaml. In der Tesla-Datei stecken die Helfer und Templates für die Wallbox-Ladekosten, in der Drucker-Datei die Tintenstand-Sensoren, im Whirlpool-Package alles von Input-Helfern bis zu Berechnungs-Templates.
Der Clou an Packages: Innerhalb einer Datei darfst du beliebige Konfigurationsbereiche mischen. So sieht ein einfaches Package aus:
1# packages/drucker.yaml
2input_number:
3 tintenstand_schwarz:
4 name: Tintenstand Schwarz
5 min: 0
6 max: 100
7 unit_of_measurement: '%'
8
9template:
10 - sensor:
11 - name: Tinte Status
12 state: >-
13 {% if states('input_number.tintenstand_schwarz') | float(0) < 20 %}
14 niedrig
15 {% else %}
16 okay
17 {% endif %}Helfer und Template-Sensor in einer Datei, sauber nach Thema gebündelt. Will ich später etwas am Drucker anpassen, mache ich genau diese eine Datei auf und finde dort alles. Kein Suchen über fünf Typ-Dateien hinweg.
Ein Hinweis aus der Praxis: Wenn du neue Dateien in den Packages-Ordner legst, starte Home Assistant einmal komplett neu. Das schnelle Neuladen erwischt frische Dateien nicht immer zuverlässig, nach einem Neustart bist du auf der sicheren Seite.
secrets.yaml: Passwörter raus aus der Konfiguration
Sobald du deine Konfiguration irgendwo teilst, im Forum, auf GitHub oder hier in den Kommentaren, dürfen keine Zugangsdaten drinstehen. Dafür gibt es secrets.yaml: Dort steht mqtt_passwort: geheim123, und in der Konfiguration schreibst du password: !secret mqtt_passwort. Die eigentliche Datei teilst du nie.
Mach dir das von Anfang an zur Gewohnheit, auch wenn du heute noch nicht vorhast, etwas zu veröffentlichen. Nachträglich alle Stellen zu finden ist mühsam.
Verläufe gezielt aufzeichnen mit dem Recorder
Ein Beispiel für etwas, das klassisch in die configuration.yaml gehört: der Recorder. Er bestimmt, welche Verläufe Home Assistant in seine Datenbank schreibt. Standardmäßig zeichnet das System ziemlich viel auf, und bei vielen Entitäten wächst die Datenbank schneller, als dir lieb ist.
Mit einer include-Liste drehst du das um und sagst dem Recorder, welche Entitäten dich wirklich interessieren:
1recorder:
2 include:
3 entities:
4 - sensor.spuelmaschine_energie
5 - sensor.waschmaschine_energie
6 - light.wohnzimmerSo landet nur der Verlauf vom Energieverbrauch der Spülmaschine oder dem Zustand der Wohnzimmerlampe in der Datenbank, der Rest fliegt raus. Das hält die Datenbank schlank und die Verlaufsansichten schnell. Wenn dich das Thema Energiedaten generell packt, schau in den Guide zum Energie-Dashboard.
UI oder YAML? Beides, mit klarer Linie
Die ehrliche Antwort auf die ewige Frage: Nutze die UI, wo sie gut ist, und YAML, wo es sein muss. Integrationen richtest du heute fast komplett über die Oberfläche ein, die landen in .storage und tauchen in deiner configuration.yaml gar nicht mehr auf. Automationen klicke ich meist im Editor zusammen.
In der configuration.yaml bleibt, was nur dort geht: Template-Sensoren, REST-Konfigurationen, ein paar Grundeinstellungen. Und genau weil dort nur noch Handarbeit liegt, lohnt sich die saubere Aufteilung in Themen-Dateien umso mehr.
Zum Bearbeiten empfehle ich das Studio-Code-Server-Add-on. Dateibaum links, Syntax-Prüfung beim Tippen, und du arbeitest direkt im Browser auf deinem Home Assistant. Alles, was ich hier zeige, geht aber genauso mit dem einfachen File Editor.
Konfiguration prüfen, neu laden, neu starten
Nach jeder Änderung gilt die eiserne Regel: Entwicklerwerkzeuge → YAML → Konfiguration prüfen, dann erst neu laden oder neu starten. Home Assistant rödelt kurz und meldet im besten Fall, dass die Konfiguration den Start nicht verhindert.
Im Video habe ich für die Demo absichtlich Quatsch in eine meiner Package-Dateien geschrieben. Witzigerweise hat die Prüfung meinen ersten Sabotageversuch einfach geschluckt, kaputtmachen ist gar nicht so leicht, wenn man es drauf anlegt. Beim zweiten Versuch kam dann die erwartete Fehlermeldung, und die ist Gold wert: Sie nennt dir die Datei, die Zeile und sogar die Spalte, in der etwas nicht stimmt. Datei öffnen, zur Zeile springen, Fehler beheben, fertig. Häufigster Kandidat ist übrigens die Einrückung, da ist YAML penibel. Mehr Strategien für die Fehlersuche findest du im Troubleshooting-Guide.
Zum Neuladen hast du zwei Wege. Unter Einstellungen → System → Neu starten gibt es neben dem kompletten Neustart auch das schnelle Neuladen, das nur die YAML-Konfiguration neu einliest. Für Änderungen an bestehenden Dateien reicht das fast immer. Bei neuen Dateien, vor allem im Packages-Ordner, mache ich den vollen Neustart. Nur dann bin ich sicher, dass wirklich alle neuen Sensoren und Helfer gezogen werden.
Noch ein letzter Tipp: Mach Backups, bevor du umstrukturierst. Eine Auslagerung in include-Dateien ist schnell gemacht, ein Tippfehler darin legt aber beim nächsten Neustart die ganze Konfiguration lahm. Mit Backup ist das ein Schulterzucken, ohne ein langer Abend.
Häufige Fragen
Kann ich automations.yaml einfach von Hand bearbeiten?
Ja, das geht. Alles, was du im Automations-Editor zusammenklickst, landet als ganz normales YAML in dieser Datei, und du kannst dort Entitäten tauschen oder Werte anpassen. Rechne nur damit, dass der Editor die Datei beim nächsten Speichern neu formatiert und Kommentare verschwinden. Danach einmal die Automationen neu laden, damit die Änderung greift.
Warum startet Home Assistant nach einer YAML-Änderung nicht mehr richtig?
In neun von zehn Fällen ist es ein Tippfehler oder eine falsche Einrückung. Schau ins Log beziehungsweise in die Meldung der Konfigurationsprüfung, dort stehen Datei, Zeile und Spalte des Fehlers. Genau deshalb solltest du vor jedem Neustart die Prüfung in den Entwicklerwerkzeugen laufen lassen, dann passiert dir das gar nicht erst.
Brauche ich Packages schon als Einsteiger?
Nein. Solange deine configuration.yaml übersichtlich ist, reichen ein paar include-Dateien völlig. Packages spielen ihre Stärke aus, wenn du viele Geräte mit jeweils mehreren Helfern, Templates und Sensoren hast. Es schadet aber auch nicht, früh damit anzufangen, denn nachträgliches Umsortieren ist deutlich mehr Arbeit.
Muss ich nach jeder Änderung Home Assistant neu starten?
Meistens nicht. Das schnelle Neuladen in den Entwicklerwerkzeugen liest die YAML-Dateien neu ein, ohne das ganze System neu zu starten. Nur bei ganz neuen Dateien, etwa im Packages-Ordner, oder bei Änderungen an Grundeinstellungen ist ein kompletter Neustart die sichere Wahl.
