OpenClaw Tutorial Teil 2: Installation

📚 Serie: OpenClaw installieren & einrichten - Teil 2 von 8
← Teil 1: Was ist OpenClaw? Überblick & Architektur | Teil 3: Modelle konfigurieren →

Nach dem theoretischen Überblick folgt nun die praktische Umsetzung: die Installation des OpenClaw-Gateway-Daemons. Ein lokal laufender Gateway bildet das Fundament, um OpenClaw auf dem Rechner zu betreiben und die Web-Oberflächen auf demselben Host zu erreichen. Die Einrichtung funktioniert auf macOS, Linux und Raspberry Pi weitgehend identisch. Windows ist ebenfalls dokumentiert; für diese Tutorial-Reihe ist WSL2 mit Ubuntu aber meist der unkompliziertere Weg.

Systemvoraussetzungen

OpenClaw setzt eine aktuelle Node.js-Umgebung voraus. Prüfe zuerst die installierte Version:

node --version
npm --version

Für aktuelle OpenClaw-Versionen sollte Node.js 22 oder neuer vorhanden sein; empfohlen ist eine aktuelle LTS-/Current-Version wie Node 24, sofern die offizielle OpenClaw-Dokumentation für deinen Installationszeitpunkt nichts anderes nennt.

Wenn Node.js fehlt:

• macOS: Installation über Homebrew ist meist am einfachsten:

  brew install node

• Linux / Raspberry Pi: Nutze entweder die Paketquelle deiner Distribution oder das offiziell empfohlene Node.js-Setup für deine Architektur. Auf Raspberry Pi OS ist wichtig, dass die Node-Version wirklich aktuell genug ist und nicht aus einer sehr alten Distribution-Quelle stammt.

• Windows: Die offizielle Windows-Dokumentation beschreibt die native Installation. Für diese Serie ist WSL2 mit Ubuntu die stabilere Variante, weil Dienstverwaltung, Pfade und spätere Sandbox-Themen näher an Linux liegen.

Zusätzlich brauchst du für die Standardinstallation curl beziehungsweise unter Windows PowerShell. Für den Docker-Weg brauchst du Docker Engine und Docker Compose.

OpenClaw installieren

Für lokale Setups ist das offizielle Installationsskript der schnellste Weg. Da Skripte aus dem Netz Code auf deinem System ausführen, ist die sauberere Variante: erst herunterladen und ansehen, dann ausführen.

macOS / Linux:

curl -fsSL https://openclaw.ai/install.sh -o /tmp/openclaw-install.sh
less /tmp/openclaw-install.sh
bash /tmp/openclaw-install.sh

Wenn du das Skript bewusst direkt ausführen möchtest, geht auch die Kurzform:

curl -fsSL https://openclaw.ai/install.sh | bash

Windows PowerShell:

iwr -useb https://openclaw.ai/install.ps1 -OutFile $env:TEMP\openclaw-install.ps1
notepad $env:TEMP\openclaw-install.ps1
powershell -ExecutionPolicy Bypass -File $env:TEMP\openclaw-install.ps1

Kurzform, wenn du dem Skript direkt vertraust:

iwr -useb https://openclaw.ai/install.ps1 | iex

Prüfe danach, ob das CLI im Pfad liegt:

command -v openclaw
openclaw --version

Unter PowerShell:

Get-Command openclaw
openclaw --version

Falls der Befehl nicht gefunden wird, öffne zuerst ein neues Terminal. Wenn das nicht reicht, prüfe den PATH und die Hinweise des Installers.

Erstkonfiguration über den Wizard

OpenClaw liefert einen interaktiven Onboarding-Wizard mit. Für ein lokales Standardsetup mit Hintergrunddienst startest du ihn so:

openclaw onboard --install-daemon

Prüfe bei abweichenden Versionen mit openclaw onboard --help, ob die Option in deiner installierten Version noch genauso heißt.

Der Assistent fragt typischerweise die wichtigsten Eckdaten ab:

• Workspace- bzw. Profil-Verzeichnis,
• Gateway-Port,
• Einrichtung als Hintergrunddienst,
• Installation beziehungsweise Bereitstellung der Web-Assets.

Für lokale Einzelplatz-Setups kannst du die Standardwerte in der Regel übernehmen. Der Gateway arbeitet nach dem Loopback-first-Modell: Die lokale Gateway-Verbindung liegt standardmäßig auf 127.0.0.1 und Port 18789. Die WebSocket-Control-Plane nutzt laut OpenClaw-Doku standardmäßig ws://127.0.0.1:18789.

Auf macOS richtet der Wizard den Dienst üblicherweise über launchd ein, auf Linux über systemd, sofern die Umgebung das unterstützt. In WSL2 hängt die Dienstverwaltung von deiner WSL-Konfiguration ab; wenn systemd dort nicht aktiv ist, starte den Gateway manuell oder aktiviere systemd für die Distribution.

Gateway starten und Web-Oberfläche öffnen

Prüfe zuerst den Status:

openclaw gateway status

Falls der Gateway noch nicht läuft, starte ihn manuell:

openclaw gateway start

Wenn deine installierte Version andere Unterbefehle verwendet, zeigt dir dieser Befehl die gültigen Optionen:

openclaw gateway --help

Sobald der Gateway aktiv ist, erreichst du die lokalen Web-Surfaces über denselben Port. Öffne zuerst:

http://127.0.0.1:18789

Falls die Root-URL in deiner Version nicht direkt auf die Oberfläche weiterleitet, prüfe die dokumentierten OpenClaw-Pfade auf demselben Port, insbesondere:

http://127.0.0.1:18789/__openclaw__/canvas/
http://127.0.0.1:18789/__openclaw__/a2ui/

Nutze bewusst 127.0.0.1 statt localhost, wenn du IPv4/IPv6-Verwechslungen ausschließen willst. localhost funktioniert auf den meisten Systemen ebenfalls, kann aber je nach Resolver zuerst auf ::1 zeigen.

Die eigentliche Agenten- und Modellkonfiguration folgt in den nächsten Teilen der Serie. Vorher sollte nur sichergestellt sein, dass CLI, Gateway und Web-Oberfläche erreichbar sind.

Alternative: Betrieb via Docker

Wenn du OpenClaw nicht direkt auf dem Host installieren möchtest, kannst du den Docker-Weg aus der offiziellen Docker-Dokumentation verwenden. Das ist sinnvoll, wenn du Abhängigkeiten isolieren oder OpenClaw reproduzierbar in einer Container-Umgebung betreiben willst.

Wichtig bei Docker:

• Starte nicht gleichzeitig einen lokalen Host-Gateway und einen Docker-Gateway auf demselben Port 18789.
• Binde den Container für lokale Tests bevorzugt nur an 127.0.0.1.
• Wenn du mehrere Gateways parallel testest, verwende getrennte Ports und getrennte Profile beziehungsweise Volumes.

Ein lokales Docker-Setup ist danach typischerweise unter folgender Adresse erreichbar:

http://127.0.0.1:18789

Die konkrete Compose-Datei und die gültigen Umgebungsvariablen solltest du direkt aus der offiziellen Docker-Dokumentation übernehmen, weil sich Image-Namen, Volumes und Startparameter ändern können.

Fehlerbehebung bei der Einrichtung

openclaw: Befehl nicht gefunden

Öffne zuerst ein neues Terminal und prüfe danach:

echo "$PATH"
command -v openclaw

Bei npm-/Node-basierten Installationen fehlt häufig das globale Paketverzeichnis im PATH. Unter macOS kann zusätzlich ein Wechsel zwischen Intel-/Apple-Silicon-Homebrew-Pfaden eine Rolle spielen.

Falsche oder zu alte Node-Version

Wenn node --version eine zu alte Version zeigt, ist oft eine alte Distribution-Version aktiv. Prüfe dann, welcher Node-Pfad verwendet wird:

which node
node --version

Installiere danach eine aktuelle Node-Version und öffne das Terminal erneut.

Port 18789 ist belegt

Prüfe, welcher Prozess den Port verwendet:

lsof -i :18789

Auf Linux geht alternativ:

ss -ltnp | grep 18789

Beende entweder den anderen Prozess oder konfiguriere OpenClaw über den Wizard beziehungsweise die dokumentierten Gateway-Optionen auf einen anderen Port. Prüfe die genaue Syntax immer mit:

openclaw gateway --help

Web-Oberfläche lädt nicht

Prüfe zuerst den Gateway-Status:

openclaw gateway status

Wenn der Gateway läuft, aber der Browser nichts anzeigt:

1. Öffne http://127.0.0.1:18789 statt localhost.
2. Prüfe die Web-Pfade /__openclaw__/canvas/ und /__openclaw__/a2ui/ auf demselben Port.
3. Starte den Onboarding-Wizard erneut, falls Web-Assets fehlen oder unvollständig installiert wurden.
4. Prüfe die Gateway-Logs über die von deiner Installation angebotenen Status-/Log-Befehle beziehungsweise über journalctl oder launchctl, wenn der Dienst darüber läuft.

Zugriff auf Raspberry Pi oder entfernten Linux-Host

Gib im Browser nicht einfach die IP-Adresse des Raspberry Pi ein, solange der Gateway nur auf Loopback gebunden ist. OpenClaw ist absichtlich loopback-first: Nicht-Loopback-Binds brauchen einen gültigen Authentifizierungspfad, zum Beispiel Token-/Passwort-Auth oder einen korrekt eingerichteten Trusted Proxy.

Für den Anfang ist ein SSH-Tunnel die sicherste Variante:

ssh -L 18789:127.0.0.1:18789 [email protected]

Danach öffnest du auf deinem eigenen Rechner:

http://127.0.0.1:18789

Für dauerhaften Remote-Zugriff ist laut OpenClaw-Netzwerkmodell ein VPN-/Tailnet-Setup wie Tailscale oder ein sauber abgesicherter Proxy vorzuziehen.

Ressourcen auf dem Raspberry Pi

Auf älteren Raspberry-Pi-Modellen, besonders Pi 3 und älter, dauert die Installation spürbar länger. Plane mindestens 1 GB freien Speicherplatz ein; mehr ist besser, wenn Docker, Logs oder zusätzliche Modelle/Assets dazukommen. Für flüssigeres Arbeiten ist ein Pi 4 oder Pi 5 mit ausreichend RAM deutlich angenehmer.

Nächste Schritte

Der Gateway-Daemon läuft, die CLI ist erreichbar und die lokalen Web-Surfaces antworten. Damit ist das technische Fundament gelegt.

Im folgenden Teil der Serie geht es an die Konfiguration der KI-Modelle. Dort wird gezeigt, wie Anbieter wie OpenAI, Anthropic oder OpenRouter angebunden, API-Schlüssel sicher verwaltet und Fallback-Routinen definiert werden.

Zu Teil 3: Modelle konfigurieren →