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 von OpenClaw auf deinem Rechner. Ziel in diesem Teil ist kein kompletter Produktivbetrieb, sondern ein sauber laufender lokaler Gateway mit erreichbarer Oberfläche und funktionierendem CLI.

Die Kernschritte sind auf macOS, Linux und Raspberry Pi ähnlich. Auf Windows gibt es inzwischen drei offizielle Wege: Windows Hub als Desktop-App, den nativen PowerShell-Installer für CLI und Gateway oder WSL2 für einen Linux-nahen Runtime-Pfad. Für diese Serie liegt der Fokus auf macOS, Linux und Raspberry Pi; wenn du auf Windows einfach nur loslegen willst, ist Windows Hub laut OpenClaw-Doku heute der einfachste Standardweg.

Was du am Ende haben solltest

Nach diesem Teil solltest du prüfen können:

• openclaw --version gibt eine Version aus,
• openclaw gateway status zeigt einen laufenden oder zumindest installierten Gateway,
• openclaw dashboard öffnet die lokale Control UI,
• du weißt, welche Diagnosebefehle bei Problemen zuerst sinnvoll sind.

Mehr muss an dieser Stelle noch nicht fertig sein. Modelle, Channels und Automationen kommen später.

Systemvoraussetzungen

OpenClaw braucht eine aktuelle Node.js-Umgebung. Prüfe zuerst, was auf deinem System vorhanden ist:

node --version
npm --version

Laut aktueller Getting-Started-Doku gilt:

• empfohlen: Node 24
• unterstützt: Node 22.19 oder neuer

Wenn Node.js fehlt:

• macOS: Homebrew ist meist der einfachste Weg. Prüfe zuerst, ob brew schon vorhanden ist:

  command -v brew

  Wenn kein Pfad zurückkommt, installiere Homebrew über die offizielle Anleitung auf brew.sh. Öffne danach ein neues Terminalfenster und prüfe noch einmal:

  brew --version

  Danach installierst du Node.js:

  brew install node

• Linux / Raspberry Pi: Nutze eine Quelle, die dir wirklich Node 22.19+ oder besser Node 24 liefert. Gerade auf Raspberry Pi OS sind die Standardpakete mancher älteren Distributionen zu alt.

• Windows: Offiziell ist heute Windows Hub der empfohlene Desktop-Pfad. Wenn du stattdessen gezielt mit CLI und Gateway arbeiten willst, kannst du den nativen PowerShell-Installer oder WSL2 verwenden.

Für die Standardinstallation brauchst du zusätzlich curl, unter Windows PowerShell. Für den Docker-Weg brauchst du Docker Desktop oder Docker Engine plus Docker Compose v2.

OpenClaw installieren

Für lokale Setups ist das offizielle Installationsskript der direkteste Weg. Wenn du bei Shell-Skripten aus dem Netz vorsichtig sein willst, lade es erst herunter, lies kurz hinein und starte es dann bewusst.

macOS / Linux:

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

Die Kurzform aus der offiziellen Doku funktioniert ebenfalls:

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

Oder direkt:

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

Wenn openclaw nicht gefunden wird, öffne zuerst ein neues Terminal. Gerade nach einer frischen Installation ist das oft schon die ganze Lösung, weil dein aktuelles Shell-Fenster den aktualisierten PATH noch nicht kennt.

Onboarding starten

Die aktuelle Getting-Started-Doku empfiehlt diesen Einstieg:

openclaw onboard --install-daemon

Der Wizard führt dich typischerweise durch:

• die Auswahl eines Modellanbieters,
• die Hinterlegung von API-Zugangsdaten,
• die lokale Gateway-Konfiguration,
• die Einrichtung des Hintergrunddienstes.

Für ein lokales Einzelplatz-Setup kannst du die Standardwerte meist übernehmen. Die Doku nennt für den Gateway standardmäßig Port 18789.

Wenn du wissen willst, welche Optionen deine installierte Version konkret kennt, prüfe:

openclaw onboard --help

Gateway prüfen und Dashboard öffnen

Nach dem Onboarding kontrollierst du zuerst, ob der Gateway erreichbar ist:

openclaw gateway status

Die aktuelle Doku nennt hier als gesundes Ziel einen laufenden Gateway auf Port 18789.

Danach öffnest du die Oberfläche über den dokumentierten Standardbefehl:

openclaw dashboard

Wenn sich die Control UI im Browser öffnet, ist dein lokales Grundsetup funktionsfähig.

Falls du lieber ohne Browser-Öffnung nur die Zieladresse sehen willst, ist bei manchen Flows auch ein --no-open-Modus verfügbar, etwa im Docker-Kontext. Für den normalen lokalen Start reicht openclaw dashboard.

Wenn der Dienst nicht sauber hochkommt

Das Onboarding installiert den Dienst normalerweise direkt mit. Falls du später manuell nachziehen oder neu aufsetzen musst, dokumentiert OpenClaw dafür einen Managed-Service-Flow:

openclaw gateway install
openclaw gateway start

Weitere Lifecycle-Befehle sind ebenfalls dokumentiert:

openclaw gateway stop
openclaw gateway restart
openclaw gateway uninstall

Wichtig: Nutze für einen Neustart möglichst openclaw gateway restart statt stop und start per Hand zu kombinieren.

Wenn du unsicher bist, welche Optionen deine Version unterstützt, hilft die CLI-Referenz direkt im Terminal:

openclaw gateway --help

Alternative: Betrieb via Docker

Docker ist laut offizieller Doku optional. Er lohnt sich vor allem dann, wenn du einen isolierten Gateway in einer Container-Umgebung willst oder den Docker-Flow gezielt testen möchtest. Für den schnellsten lokalen Entwicklungsweg ist der normale Installer meist einfacher.

Der offizielle Docker-Weg sieht nicht nach einer beliebigen Compose-Datei aus, sondern startet aus dem OpenClaw-Repo:

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

Wenn du statt lokalem Build lieber ein vorgefertigtes Image verwenden willst, nennt die Doku als Beispiel:

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

Laut offizieller Docker-Doku übernimmt das Setup-Skript anschließend automatisch zentrale Schritte wie:

• Onboarding,
• Erzeugung eines Gateway-Tokens,
• Schreiben wichtiger Werte in .env,
• Start des Gateways per Docker Compose.

Die Control UI erreichst du danach über:

http://127.0.0.1:18789/

Je nach Setup musst du in der Oberfläche anschließend noch das konfigurierte Shared Secret oder Passwort eintragen. Die Doku verweist dafür auf die beim Setup erzeugten Werte.

Wichtig bei Docker:

• Lass nicht parallel einen Host-Gateway und einen Docker-Gateway auf demselben Port laufen.
• Plane mindestens 2 GB RAM für den Image-Build ein. Die offizielle Doku warnt sonst ausdrücklich vor OOM-Fehlern.
• Nutze Docker eher für isolierte oder reproduzierbare Deployments, nicht automatisch als Standard für deinen Alltags-Laptop.

Fehlerbehebung bei der Einrichtung

openclaw: Befehl nicht gefunden

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

echo "$PATH"
command -v openclaw

Wenn der Pfad weiter fehlt, war die Installation entweder nicht vollständig oder dein Shell-Profil wurde noch nicht neu geladen.

Falsche oder zu alte Node-Version

Prüfe, welche Binary du tatsächlich benutzt:

which node
node --version

Wenn eine alte Version aktiv ist, installiere Node 24 oder mindestens 22.19+ aus einer aktuellen Quelle und öffne das Terminal erneut.

Gateway läuft nicht sauber

Die wichtigsten Diagnosebefehle sind aktuell:

openclaw gateway status
openclaw doctor
openclaw logs --follow

openclaw gateway status zeigt den Dienststatus plus Konnektivitätsprobe. openclaw doctor hilft bei Konfigurations- und Service-Problemen. openclaw logs --follow ist der schnelle Weg in die laufenden Gateway-Logs.

Port 18789 ist belegt

Prüfe, welcher Prozess den Port verwendet:

lsof -i :18789

Auf Linux geht alternativ:

ss -ltnp | grep 18789

Laut FAQ ist 18789 der Standardport für den multiplexed Gateway-Port. Wenn dort bereits etwas anderes lauscht, stoppe den Konfliktprozess oder installiere den Gateway mit einem abweichenden Port neu.

Dashboard lädt nicht

Prüfe zuerst:

openclaw gateway status

Wenn der Gateway laut Status läuft, aber die Oberfläche nicht erreichbar ist:

1. Starte openclaw dashboard erneut.
2. Prüfe, ob deine Version wirklich auf Port 18789 gebunden ist.
3. Führe openclaw doctor aus.
4. Prüfe die Logs mit openclaw logs --follow.

Im Docker-Setup kommt noch ein typischer Stolperstein dazu: Die Seite kann laden, aber noch nach Token oder Passwort fragen. Dann fehlt nicht die UI, sondern nur der passende Auth-Wert aus dem Setup.

Zugriff auf Raspberry Pi oder entfernten Linux-Host

Öffne einen frisch installierten Gateway nicht blind im Netzwerk. OpenClaw arbeitet standardmäßig loopback-first. Für einen schnellen und sicheren Erstzugriff ist ein SSH-Tunnel die sauberste Variante:

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

Danach öffnest du auf deinem eigenen Rechner wieder die lokale Adresse oder openclaw dashboard gegen den Tunnel.

Die offizielle Remote-Doku dokumentiert SSH-Tunnel explizit als Standardweg für entfernte Gateways, wenn diese nur auf Loopback gebunden sind.

Raspberry Pi: realistische Erwartungen

Auf älteren Raspberry-Pi-Modellen dauert die Installation spürbar länger. Für Docker, Logs und spätere Zusatzdienste solltest du freien Speicher und RAM nicht zu knapp kalkulieren. Ein Pi 4 oder Pi 5 ist für OpenClaw deutlich angenehmer als sehr alte Modelle.

Kurzfazit

Wenn openclaw --version, openclaw gateway status und openclaw dashboard funktionieren, steht das Fundament. Genau das ist das Ziel dieses Teils: kein Vollausbau, sondern ein sauberer lokaler Startpunkt.

Im nächsten Teil geht es an die Modellkonfiguration: Anbieter anbinden, Zugangsdaten hinterlegen und sinnvolle Defaults setzen.

Zu Teil 3: Modelle konfigurieren →