Home Assistant OS per WLAN – headless einrichten ohne Kabel

Passende Hardware im Überblick

Boards für Home Assistant OS:
Raspberry Pi 5 mit 8GB RAM – die Empfehlung (Link)*
Raspberry Pi 5 mit 16GB RAM für große Installationen (Link)*
Raspberry Pi 5 mit 4GB RAM – reicht für den Einstieg (Link)*
db-tronic Pi 5 Komplett-Set mit Gehäuse und Netzteil (Link)*
Raspberry Pi 4 Starter-Set – wenn es günstig sein soll (Link)*
Home Assistant Green – fertige Box, aber nur mit LAN-Buchse (Link)*

Datenträger für den CONFIG-Stick und das System:
SanDisk Extreme A2 128GB microSD (Link)*
Günstige 32GB microSD-Karte (Link)*
UGREEN USB-3-Kartenleser – zum Beschreiben am PC (Link)*
UGREEN 2-in-1-Kartenleser für SD und microSD (Link)*
Intenso M.2 NVMe SSD 500GB – für den Dauerbetrieb (Link)*
Geekworm X1001 M.2-HAT für den Pi 5 (Link)*

Strom und Netzwerk für den 24/7-Betrieb:
Offizielles 27-W-Netzteil für den Pi 5 (Link)*
Geekworm X1200 USV – überbrückt Stromausfälle (Link)*
Waveshare PoE-HAT (F) für den Pi 5 – Strom und Netz über ein Kabel (Link)*
GeeekPi P33 mit PoE und NVMe-Steckplatz (Link)*

Kurz gesagt: Wie bringt man Home Assistant OS ins WLAN?

Die Kurzfassung:

• Der Imager hilft nicht: Die WLAN-Einstellungen im Raspberry Pi Imager greifen nur bei Raspberry Pi OS. Home Assistant OS ignoriert sie vollständig.
• Der offizielle Weg: Ein Datenträger mit der Bezeichnung CONFIG, darin ein Ordner network und darin eine Datei namens my-network im NetworkManager-Format.
• Kein Dateiende, Unix-Zeilenumbrüche: Die Datei heißt exakt my-network – ohne .txt – und muss mit LF statt CRLF gespeichert werden.
• Import: Beim ersten Start liest das System den Stick selbst ein. Läuft die Installation schon, hilft ha os import an der Konsole.
• Bequemer geht es per Kabel: Einmal mit LAN starten, dann unter Einstellungen > System > Netzwerk das WLAN eintragen und danach das Kabel ziehen.
• Für Dauerläufer gilt trotzdem: Kabel schlägt Funk – die Zentrale des Smart Homes sollte nicht am schwächsten Glied der Kette hängen.

Warum der Raspberry Pi Imager beim Home Assistant OS WLAN nicht hilft

Wer einen Pi mit Raspberry Pi OS aufsetzt, kennt den Komfort: Im Imager klappt man die Einstellungen auf, trägt SSID und Passwort ein, und der Pi hängt beim ersten Start im Netz. Beim Home Assistant OS WLAN funktioniert genau das nicht – und zwar aus einem systematischen Grund, nicht wegen eines Fehlers.

Der Imager schreibt seine Vorgaben in eine Startdatei auf der Boot-Partition, die Raspberry Pi OS beim ersten Hochfahren ausliest. Home Assistant OS ist aber kein Debian-Abkömmling, sondern ein eigenständiges, minimales Betriebssystem, das ausschließlich Home Assistant und seine Container betreibt. Es kennt diesen Mechanismus nicht und lässt die Datei unangetastet liegen.

Stattdessen verwaltet Home Assistant OS sämtliche Verbindungen über NetworkManager – dieselbe Komponente, die auch auf vielen Linux-Desktops die Netzwerkverbindungen steuert. NetworkManager erwartet seine Konfiguration als sogenannte Keyfiles: kleine Textdateien mit Abschnitten in eckigen Klammern. Genau so eine Datei muss man dem System unterschieben, wenn der Pi ohne Netzwerkkabel starten soll.

Das klingt umständlicher, als es ist. Man braucht keinen Editor auf dem Pi und keinen Zugang zur Kommandozeile – die Datei entsteht am PC oder Mac und wandert über einen USB-Stick auf den Pi. Wer schon einmal headless gearbeitet hat, kennt das Prinzip: Konfiguration vorbereiten, Datenträger anstecken, booten.

Home Assistant OS WLAN über den CONFIG-Stick einrichten – Schritt für Schritt

1. USB-Stick vorbereiten: Einen beliebigen kleinen Stick mit FAT32 formatieren und ihm den Datenträgernamen CONFIG geben – in Großbuchstaben. Gemeint ist die Bezeichnung des Datenträgers, nicht ein Ordner darauf.
2. Ordner anlegen: Auf dem Stick einen Ordner network erstellen, klein geschrieben. Andere Schreibweisen werden nicht erkannt.
3. Datei erstellen: In diesem Ordner eine Textdatei mit dem Namen my-network anlegen – ohne jede Endung. Unter Windows dazu vorher im Explorer die Anzeige der Dateinamenerweiterungen aktivieren, sonst entsteht unbemerkt my-network.txt.
4. Zugangsdaten eintragen: Den Inhalt aus dem nächsten Abschnitt einfügen, SSID und Passwort ersetzen und eine eigene UUID eintragen. Speichern mit Unix-Zeilenenden (LF) – in Notepad++ oder VS Code ist das ein Klick in der Statusleiste.
5. Stick anstecken und starten: Den Stick in den Pi stecken, die vorbereitete Karte oder SSD einlegen und das Gerät einschalten. Beim ersten Hochfahren übernimmt Home Assistant OS die Datei automatisch.
6. Import anstoßen, falls nötig: Läuft das System bereits oder tut sich nichts, hilft die Konsole an Monitor und Tastatur: dort ha os import eingeben. Mit ha network info lässt sich anschließend prüfen, ob wlan0 eine IP-Adresse bekommen hat.
7. Erreichbarkeit testen: Im Browser http://homeassistant.local:8123 aufrufen. Klappt die Namensauflösung nicht, hilft ein Blick in die Geräteliste des Routers, um die IP-Adresse zu finden.
8. Stick abziehen: Nach erfolgreichem Import ist die Verbindung dauerhaft im System gespeichert. Der Stick wird nicht mehr gebraucht – und sollte auch nicht steckenbleiben, weil das WLAN-Passwort im Klartext darauf steht.

Die Datei my-network richtig aufbauen

Der Inhalt folgt dem Keyfile-Format von NetworkManager. Für ein normales WPA2- oder WPA3-Netz sieht er so aus:

[connection]
id=my-network
uuid=72111c67-4a5d-4d5c-925e-f8ee26efb3c3
type=802-11-wireless

[802-11-wireless]
mode=infrastructure
ssid=MEIN_WLAN

[802-11-wireless-security]
auth-alg=open
key-mgmt=wpa-psk
psk=MEIN_WLAN_PASSWORT

[ipv4]
method=auto

[ipv6]
addr-gen-mode=stable-privacy
method=auto

Wichtig ist die UUID: Sie muss eindeutig sein und darf nicht einfach aus einer Anleitung abgeschrieben werden, wenn im selben Netz mehrere Geräte auf diese Weise eingerichtet werden. Unter Linux und macOS liefert uuidgen im Terminal eine passende Zeichenkette, ansonsten tut es jeder UUID-Generator im Browser.

Wer statt eines USB-Sticks lieber ohne zusätzliche Hardware arbeitet, kann den Ordner CONFIG mit demselben Inhalt auch direkt auf die kleine Boot-Partition der frisch geschriebenen Speicherkarte legen. Diese Partition erscheint nach dem Schreiben des Abbilds am PC und ist der einzige Teil der Karte, den Windows lesen kann.

Feste IP-Adresse vergeben – im Keyfile oder in der Oberfläche

Eine Smart-Home-Zentrale, deren Adresse sich gelegentlich ändert, sorgt für unnötigen Ärger: Lesezeichen zeigen ins Leere, Weiterleitungen brechen, und Integrationen mit fest eingetragener Adresse verlieren die Verbindung. Deshalb gehört zur Ersteinrichtung fast immer auch eine feste IP-Adresse.

Im Keyfile ersetzt man dazu den Abschnitt [ipv4] durch die manuelle Variante:

[ipv4]
method=manual
address=192.168.1.111/24;192.168.1.1
dns=192.168.1.1;

Vor dem Semikolon stehen IP-Adresse und Präfixlänge, dahinter das Gateway – also in aller Regel der Router. Die Adresse muss außerhalb des DHCP-Bereichs liegen, sonst kann der Router sie ein zweites Mal vergeben. Alternativ, und für die meisten Heimnetze noch bequemer: Man belässt es bei method=auto und trägt im Router eine feste Zuordnung zur MAC-Adresse ein. In einer FRITZ!Box heißt das „Diesem Netzwerkgerät immer die gleiche IPv4-Adresse zuweisen".

Alternative: erst per Kabel starten, dann auf Funk umstellen

Wenn ein Netzwerkkabel für die Ersteinrichtung erreichbar ist, führt der deutlich entspanntere Weg über die Oberfläche. Man startet Home Assistant auf dem Raspberry Pi ganz normal mit LAN, richtet Benutzer und Standort ein und wechselt anschließend zu Einstellungen > System > Netzwerk.

Dort taucht der WLAN-Adapter als eigener Eintrag auf. Man wählt das gewünschte Netz aus der Liste, gibt das Passwort ein und stellt bei Bedarf gleich im selben Dialog die IPv4-Konfiguration von automatisch auf statisch um. Ist die SSID versteckt, lässt sie sich von Hand eintragen. Nach dem Speichern kann das Kabel gezogen und das Gerät neu gestartet werden – die Funkverbindung greift dann selbstständig.

Ein Sicherheitsnetz gehört dazu: ein Backup und das Wissen, dass sich die Netzwerkeinstellungen über die Konsole korrigieren lassen – ha network info zeigt den Zustand, ha network update ändert ihn. Wer sich ausgesperrt hat, steckt einfach wieder ein Kabel ein.

Kabel oder WLAN – was für einen Dauerläufer besser ist

Die Konfiguration über den CONFIG-Stick funktioniert zuverlässig, doch die ehrlichere Frage lautet: Sollte die Zentrale des Smart Homes überhaupt per Funk hängen? Berichte aus der Community fallen hier ziemlich eindeutig aus – die meisten schwer greifbaren Aussetzer in Automationen haben ihre Wurzel im Netzwerk, nicht in Home Assistant selbst.

Besonders der dritte Punkt wird gern unterschätzt: Ein USB-Funkstick für Zigbee arbeitet im selben 2,4-GHz-Band wie das WLAN. Steckt er direkt neben dem Board, das gleichzeitig funkt, leidet die Reichweite spürbar. Ein Verlängerungskabel für den Stick und ein Netzwerkkabel für den Pi lösen dieses Problem schlagartig.

Fehler und Stolpersteine bei der WLAN-Einrichtung

• Der Stick heißt nicht CONFIG: Gemeint ist der Datenträgername, den man beim Formatieren vergibt – nicht ein Ordner mit diesem Namen. Kleinschreibung oder Zusätze wie CONFIG1 werden ignoriert.
• Versteckte Dateiendung: Windows hängt in der Standardeinstellung unsichtbar .txt an. Die Datei muss exakt my-network heißen, sonst passiert beim Start nichts.
• Windows-Zeilenenden: Mit CRLF gespeicherte Dateien werden nicht sauber gelesen. Der Editor muss auf LF umgestellt werden – ebenso stört ein UTF-8-BOM am Dateianfang.
• Tippfehler in der SSID: Groß- und Kleinschreibung zählt, und ein Leerzeichen am Zeilenende gehört mit zum Namen. Die SSID gehört ohne Anführungszeichen hinter das Gleichheitszeichen.
• Sonderzeichen im Passwort: Auch das Passwort steht ohne Anführungszeichen da. Ein Rautezeichen am Zeilenanfang macht die Zeile zum Kommentar, und angehängte Leerzeichen wandern stillschweigend mit ins Passwort.
• 5-GHz-Netz nicht sichtbar: Ältere Modelle wie der Pi 3B oder der Zero 2 W funken ausschließlich auf 2,4 GHz. Und selbst bei neueren Boards bleiben die oberen 5-GHz-Kanäle mitunter unsichtbar, solange der Ländercode nicht gesetzt ist. Ein gemeinsamer Name für beide Bänder im Router entschärft das.
• Verstecktes Netz: Ohne die Zeile hidden=true sucht der Pi vergeblich. Fürs Erste ist es einfacher, die SSID-Übertragung im Router vorübergehend einzuschalten.
• Doppelte UUID: Zwei Geräte mit derselben UUID im Netz führen zu sprunghaften Adressen. Für jedes Gerät eine neue erzeugen.

Häufige Fragen zu Home Assistant OS und WLAN

Kann ich das WLAN nicht einfach im Raspberry Pi Imager eintragen?
Nein. Die Vorgaben aus dem Imager wertet nur Raspberry Pi OS aus. Home Assistant OS liest sie nicht und startet ohne Verbindung – hier führt kein Weg an der Datei my-network oder an einem Kabel vorbei.

Wie muss der USB-Stick formatiert sein?
FAT32 ist die sichere Wahl. Entscheidend ist der Datenträgername CONFIG in Großbuchstaben; die Größe spielt keine Rolle, ein alter 2-GB-Stick genügt vollkommen.

Woher weiß ich, ob der Import geklappt hat?
An der Konsole zeigt ha network info alle Schnittstellen mit ihren Adressen. Steht bei wlan0 eine IP-Adresse aus dem Heimnetz, ist alles in Ordnung. Andernfalls hilft ein erneutes ha os import.

Muss der Stick stecken bleiben?
Nein. Nach dem Import liegt die Verbindung dauerhaft im System. Weil das WLAN-Passwort im Klartext auf dem Stick steht, sollte er nach der Einrichtung sogar bewusst abgezogen und die Datei gelöscht werden.

Funktioniert der gleiche Weg auch für eine feste IP-Adresse?
Ja. Statt method=auto trägt man method=manual mit Adresse, Gateway und DNS ein. Genauso gut lässt sich die Adresse nachträglich in den Netzwerkeinstellungen der Oberfläche festlegen.

Was ist mit Home Assistant in einer virtuellen Maschine?
Dort stellt sich die Frage nicht: Eine Installation unter Proxmox bekommt ihr Netz vom Wirtssystem. Die CONFIG-Methode betrifft nur Geräte, die direkt mit Home Assistant OS starten.

Kann ich mein Gerät später wieder auf Kabel umstellen?
Ja, jederzeit. Kabel einstecken, in den Netzwerkeinstellungen die WLAN-Verbindung deaktivieren – der Rest der Installation samt Geräten und Automationen bleibt davon unberührt.

Fazit

Das Home Assistant OS WLAN über einen CONFIG-Stick einzurichten, ist kein Hexenwerk – es ist nur ungewohnt, weil der bequeme Umweg über den Imager hier nicht existiert. Wer sauber arbeitet, den Datenträger korrekt beschriftet, die Datei ohne Endung anlegt und auf Unix-Zeilenenden achtet, ist in zehn Minuten fertig. Unsere klare Empfehlung lautet trotzdem: Nutze diesen Weg für die Ersteinrichtung, nicht als Dauerlösung. Eine Smart-Home-Zentrale steuert Licht, Heizung und Türschlösser – sie sollte nicht davon abhängen, ob der Nachbar gerade einen neuen Repeater aufgestellt hat. Liegt keine Leitung am Aufstellort, sind ein PoE-HAT oder ein Powerline-Adapter die bessere Investition als jede Optimierung am Funk. Und wenn es doch beim WLAN bleibt: feste IP-Adresse vergeben, damit die Zentrale morgen noch dort erreichbar ist, wo sie heute war.

* = Affiliate Link (raspi-config.de ist Teilnehmer des Partnerprogramms von Amazon EU, das zur Bereitstellung eines Mediums für Websites konzipiert wurde, mittels dessen durch die Platzierung von Werbeanzeigen und Links zu Amazon.de Werbekostenerstattung verdient werden kann.)