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 Installation von OpenClaw auf deinem Rechner. Am Ende dieses Teils soll ein lokaler Gateway als Hintergrunddienst laufen und seine Control UI erreichbar sein. Die Feinabstimmung von Modellen, Channels und Automationen folgt in den nächsten Teilen.

Die Kernschritte sind auf macOS, Linux und Raspberry Pi ähnlich. Unter Windows gibt es drei offizielle Wege: Windows Hub als Desktop-App, den PowerShell-Installer für CLI und Gateway sowie WSL2 für einen Linux-nahen Gateway-Betrieb. Diese Anleitung konzentriert sich auf macOS, Linux und Raspberry Pi. Für einen einfachen Windows-Desktop-Start empfiehlt die offizielle Windows-Dokumentation Windows Hub.

Das brauchst du

Die offizielle Getting-Started-Dokumentation nennt Node.js 22.22.3+, 24.15+ oder 25.9+ als unterstützte Stände. Node 26 ist dort als empfohlene Runtime ausgewiesen.

Prüfe deine Installation mit:

node --version
npm --version

Zusätzlich brauchst du unter macOS oder Linux curl, unter Windows PowerShell und für die Docker-Variante Docker Desktop oder Docker Engine mit Docker Compose v2. Für den vollständigen Onboarding-Durchlauf benötigst du außerdem einen API-Schlüssel oder einen anderen unterstützten Anmeldeweg für einen Modellanbieter.

Der Onboarding-Wizard fragt die Zugangsdaten des Modellanbieters ab. Wie du anschließend Modelle auswählst und sinnvolle Defaults setzt, behandelt Teil 3 der Serie.

Node.js auf macOS vorbereiten

Wenn node --version fehlt oder eine nicht unterstützte Version zeigt, kannst du auf macOS Homebrew verwenden. Prüfe zuerst, ob Homebrew vorhanden ist:

command -v brew

Kommt kein Pfad zurück, installierst du Homebrew nach der offiziellen Anleitung auf brew.sh. Öffne anschließend ein neues Terminal und prüfe die Installation:

brew --version

Installiere danach Node.js und kontrolliere die tatsächlich aktive Version:

brew install node
node --version

Vergleiche die Ausgabe anschließend mit den verlinkten Mindestständen. Die Hauptversion allein reicht für diese Prüfung nicht aus.

Linux und Raspberry Pi vorbereiten

Die Pakete älterer Distributionen enthalten häufig eine zu alte Node.js-Version. Nutze deshalb eine aktuelle Paketquelle und prüfe anschließend immer node --version.

Für einen Raspberry Pi empfiehlt sich ein aktuelles 64-Bit-Raspberry-Pi-OS. Aktualisiere das System und installiere die benötigten Werkzeuge:

sudo apt update
sudo apt upgrade -y
sudo apt install -y git curl build-essential

Die offizielle Raspberry-Pi-Anleitung verwendet Node.js 24 über NodeSource:

curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt install -y nodejs
node --version
npm --version

Für Node 24 verlangt die Getting-Started-Dokumentation mindestens Version 24.15. Eine ältere Ausgabe von node --version erfüllt die Voraussetzung nicht.

Stelle außerdem die korrekte Zeitzone ein, damit spätere Zeitpläne und Erinnerungen stimmen:

timedatectl list-timezones
sudo timedatectl set-timezone Europe/Berlin
timedatectl

Ersetze Europe/Berlin, wenn der Pi in einer anderen Zeitzone läuft.

OpenClaw installieren

Für lokale Setups ist das offizielle Installationsskript der direkte Weg. Du kannst es vor dem Ausführen in einer temporären Datei prüfen.

macOS und Linux

installer_file="$(mktemp)"
curl -fsSL https://openclaw.ai/install.sh -o "$installer_file"
less "$installer_file"
bash "$installer_file"
rm -f "$installer_file"

Die Kurzform aus der offiziellen Installationsanleitung lautet:

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

Windows PowerShell

$installerFile = Join-Path $env:TEMP ("openclaw-install-" + [guid]::NewGuid() + ".ps1")
iwr -useb https://openclaw.ai/install.ps1 -OutFile $installerFile
notepad $installerFile
powershell -ExecutionPolicy Bypass -File $installerFile
Remove-Item $installerFile

Der dokumentierte Direktaufruf lautet:

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

Öffne nach der Installation ein neues Terminal und prüfe das CLI.

Unter macOS und Linux:

command -v openclaw
openclaw --version

Unter PowerShell:

Get-Command openclaw
openclaw --version

Die Prüfung muss einen ausführbaren Befehl und eine OpenClaw-Version liefern. Wird openclaw nicht gefunden, hat das aktuelle Terminal häufig noch den alten PATH geladen.

Onboarding und Hintergrunddienst einrichten

Starte den in der Getting-Started-Dokumentation beschriebenen Onboarding-Ablauf mit:

openclaw onboard --install-daemon

Der Wizard führt dich durch die Anmeldung beim Modellanbieter, die lokale Gateway-Konfiguration und die Installation des Hintergrunddienstes. Optionale Channels und Erweiterungen kannst du zunächst überspringen und später mit openclaw configure ergänzen.

Welche Optionen deine installierte Version unterstützt, zeigt:

openclaw onboard --help

Nach einem erfolgreichen Durchlauf sollte der Gateway-Dienst installiert und gestartet sein.

Gateway und Control UI prüfen

Prüfe zuerst Dienst und Verbindung:

openclaw gateway status

Für einen eindeutigen Abschlusstest kannst du verlangen, dass auch die RPC-Probe erfolgreich ist:

openclaw gateway status --require-rpc

Der zweite Befehl endet mit einem Fehlerstatus, wenn der Dienst zwar existiert, die RPC-Verbindung aber nicht funktioniert.

Öffne anschließend die Control UI:

openclaw dashboard

Der Befehl öffnet die Oberfläche mit der aktuellen Gateway-Authentifizierung im Browser. Wenn die Seite lädt und openclaw gateway status --require-rpc erfolgreich endet, ist das lokale Grundsetup funktionsfähig.

Die Getting-Started-Dokumentation nennt Port 18789 als Standardport des Gateways. Maßgeblich bleibt die Konfiguration deiner Installation.

Gateway-Dienst verwalten

Das Onboarding mit --install-daemon richtet den Dienst normalerweise bereits ein. Wenn du ihn später neu installieren musst, verwendest du:

openclaw gateway install
openclaw gateway start

Für den laufenden Betrieb stehen außerdem diese Lifecycle-Befehle bereit:

openclaw gateway stop
openclaw gateway restart
openclaw gateway uninstall

openclaw gateway uninstall entfernt den verwalteten Dienst. Lösche Konfigurations- oder Zustandsdateien nicht pauschal, wenn du nur den Autostart zurücknehmen möchtest.

Die Befehle und Optionen deiner installierten Version findest du hier:

openclaw gateway --help
openclaw gateway install --help

Raspberry Pi als entfernter Gateway

Auf dem Pi läuft das gleiche Onboarding:

openclaw onboard --install-daemon
openclaw gateway status --require-rpc

Bei einer systemd-Benutzerinstallation kannst du zusätzlich den Dienststatus und seine Logs prüfen:

systemctl --user status openclaw-gateway.service
journalctl --user -u openclaw-gateway.service -f

Beende die laufende Logansicht mit Ctrl+C.

OpenClaw bindet einen lokalen Gateway standardmäßig an Loopback. Für den Zugriff von deinem eigenen Rechner musst du ihn deshalb nicht ungeschützt im LAN oder Internet freigeben. Lass dir zunächst auf dem Pi die Dashboard-URL ausgeben:

ssh pi@raspberrypi.local 'openclaw dashboard --no-open'

Ersetze Benutzername und Host durch die Daten deines Pi. Öffne danach in einem zweiten lokalen Terminal den SSH-Tunnel:

ssh -N -L 18789:127.0.0.1:18789 pi@raspberrypi.local

Solange dieser Befehl läuft, öffnest du auf deinem eigenen Rechner genau die zuvor ausgegebene Dashboard-URL. Sie zeigt über den lokalen Port 18789 auf den Gateway des Pi. Die URL kann ein aktuelles Zugriffstoken enthalten; teile sie deshalb nicht und veröffentliche sie nicht in Screenshots oder Logs.

Wenn die Verbindung scheitert, prüfe auf dem Pi zuerst openclaw gateway status --require-rpc und danach den systemd-Dienst. Schlägt bereits die SSH-Verbindung fehl, liegt das Problem noch vor OpenClaw. Prüfe dann Hostname, Benutzerkonto, Netzwerk und SSH-Zugang.

Die Raspberry-Pi-Dokumentation empfiehlt auf Geräten mit höchstens 2 GB RAM zusätzlichen Swap. Für einen dauerhaft betriebenen Gateway ist dort außerdem eine USB-SSD als belastbarere Alternative zur stark beschriebenen SD-Karte genannt.

Alternative: Docker

Docker ist optional. Der Weg eignet sich für einen isolierten Gateway oder einen Host, auf dem du keine lokale Node.js-Installation pflegen möchtest. Die offizielle Docker-Dokumentation verlangt für den Image-Build mindestens 2 GB RAM und Docker Compose v2.

Der offizielle Ablauf startet im OpenClaw-Repository:

git clone https://github.com/openclaw/openclaw.git
cd openclaw
./scripts/docker/setup.sh

Das Skript baut standardmäßig ein lokales Image. Für das offizielle vorgefertigte Image setzt du vor dem Start:

export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./scripts/docker/setup.sh

Das Setup übernimmt Onboarding, Gateway-Authentifizierung und den Start per Docker Compose. Folge anschließend der ausgegebenen Dashboard-Adresse. Häufig ist sie unter http://127.0.0.1:18789/ erreichbar; bei einer abweichenden Konfiguration gilt die vom Setup ausgegebene Adresse.

Achte darauf, nicht gleichzeitig einen Host-Gateway und einen Docker-Gateway an denselben Port zu binden. Lädt die Control UI, verlangt aber ein Token oder Passwort, ist der Webserver erreichbar. Verwende dann die vom Docker-Setup erzeugte Gateway-Authentifizierung.

Fehlerbehebung

openclaw: Befehl nicht gefunden

Öffne ein neues Terminal und prüfe:

echo "$PATH"
command -v openclaw

Bleibt die zweite Ausgabe leer, wurde das CLI entweder nicht vollständig installiert oder sein Verzeichnis fehlt im PATH.

Node.js ist zu alt

Prüfe Binary und Version gemeinsam:

which node
node --version

Vergleiche die Ausgabe mit den Mindestständen aus der oben verlinkten Getting-Started-Dokumentation. Aktualisiere eine zu alte Installation aus einer aktuellen Quelle und öffne danach ein neues Terminal.

Der Gateway-Dienst läuft nicht

Beginne mit den belegten Diagnosebefehlen:

openclaw gateway status --require-rpc
openclaw doctor

Auf einem Raspberry Pi oder Linux-Host mit systemd-Benutzerdienst folgen:

systemctl --user status openclaw-gateway.service
journalctl --user -u openclaw-gateway.service -f

openclaw gateway status trennt Dienststatus und Konnektivitätsprobe. openclaw doctor prüft Konfigurations- und Service-Probleme.

Port 18789 ist belegt

Auf macOS prüfst du den Port mit:

lsof -i :18789

Auf Linux:

ss -ltnp | grep 18789

Stoppe nicht wahllos Prozesse. Kläre zuerst, ob bereits ein OpenClaw-Gateway läuft oder ob deine Installation absichtlich einen anderen Port verwendet.

Die Control UI lädt nicht

Prüfe in dieser Reihenfolge:

1. openclaw gateway status --require-rpc
2. openclaw dashboard
3. openclaw doctor
4. den Dienststatus beziehungsweise das systemd-Journal

Bei einem entfernten Gateway muss außerdem der SSH-Tunnel aktiv bleiben. Lädt die Seite, fordert aber Zugangsdaten an, prüfe die vom Dashboard- oder Docker-Setup ausgegebene Authentifizierung.

Kernpunkte

Die Installation ist abgeschlossen, wenn openclaw --version eine Version ausgibt, openclaw gateway status --require-rpc erfolgreich endet und openclaw dashboard die Control UI öffnet. Auf einem Raspberry Pi kommt der lokale Zugriff über die mit openclaw dashboard --no-open ausgegebene URL und den laufenden SSH-Tunnel zustande.

Damit steht ein überprüfbarer Ausgangspunkt für die weitere Konfiguration. Im nächsten Teil bindest du einen Modellanbieter an und legst sinnvolle Modell-Defaults fest.

Zu Teil 3: Modelle konfigurieren →