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 die praktische Umsetzung: die Installation des OpenClaw-Gateway-Daemons. Der lokale Gateway ist das Fundament, damit OpenClaw auf deinem Rechner läuft und die Web-Oberflächen über denselben Host erreichbar sind. Die Einrichtung funktioniert auf macOS, Linux und Raspberry Pi weitgehend ähnlich. 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 mindestens Node.js 22.16 oder neuer vorhanden sein. Empfehlenswert ist eine aktuelle LTS- oder 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 Distributionsquelle 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 meist der direkteste 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. Nutze sie nur, wenn du der Quelle vertraust und die offizielle Dokumentation für deine Version geprüft hast:

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- beziehungsweise 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-Dokumentation 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. Die folgenden Gateway-Befehle sind als lokale Checkliste gedacht; gleiche sie bei abweichenden Versionen mit der offiziellen OpenClaw-Dokumentation und der Hilfe deiner Installation ab.

: Quelle: https://docs.openclaw.ai/start/getting-started
openclaw gateway status

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

: Quelle: https://docs.openclaw.ai/start/getting-started
openclaw gateway start

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

: Quelle: https://docs.openclaw.ai/start/getting-started
openclaw gateway --help

Sobald der Gateway aktiv ist, erreichst du die lokalen Web-Surfaces über denselben Port. Öffne zuerst die lokale Root-Adresse auf 127.0.0.1 und Port 18789.

Falls die Root-Adresse in deiner Version nicht direkt auf eine Oberfläche weiterleitet, prüfe die dokumentierten OpenClaw-Pfade auf demselben Port, insbesondere die Canvas- und A2UI-Pfade unter __openclaw__.

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 ebenfalls über 127.0.0.1 und Port 18789 erreichbar.

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- oder Node-basierten Installationen fehlt häufig das globale Paketverzeichnis im PATH. Unter macOS kann zusätzlich ein Wechsel zwischen Intel- und 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 Distributionsversion 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:

: Quelle: https://docs.openclaw.ai/start/getting-started
openclaw gateway --help

Web-Oberfläche lädt nicht

Prüfe zuerst den Gateway-Status:

: Quelle: https://docs.openclaw.ai/start/getting-started
openclaw gateway status

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

1. Öffne die lokale Adresse über 127.0.0.1 statt über localhost.
2. Prüfe die Canvas- und A2UI-Pfade auf demselben Port gegen die offizielle Dokumentation deiner installierten Version.
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- oder 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- oder 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 pi@raspberrypi.local

Danach öffnest du auf deinem eigenen Rechner die lokale Adresse auf 127.0.0.1 und Port 18789.

Für dauerhaften Remote-Zugriff ist laut OpenClaw-Netzwerkmodell ein VPN- oder 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 und Assets dazukommen. Für flüssigeres Arbeiten ist ein Pi 4 oder Pi 5 mit ausreichend RAM deutlich angenehmer.

Zusammenfassung

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 →