2026 OpenClaw: Der vollständigste Installations- und Konfigurationsleitfaden — Schritt-für-Schritt-Tutorial von null bis zum Lauf

2. Schmerzpunkte

1. Grenze: Tutorials enden bei „erfolgreich gestartet“. Ein Willkommensbanner im Terminal bedeutet nicht, dass das Modell verbunden ist, Datei-Tools funktionieren oder das Gateway Nachrichten empfängt. OpenClaw ist erst wirklich nutzbar, wenn Abhängigkeiten und Node-Versionen, onboard + Modellverbindung, Gateway auf 18789, Dashboard-Zugriff, Berechtigungsgrenzen, nachvollziehbare Logs und ein Praxisfall mit geringem Risiko alle bestehen.
2. Versteckte Kosten: Keys und Pfade verstreut. API-Keys nur in Notizen, openclaw.json5 nicht synchron mit .env, Workspace zeigt auf das gesamte Home-Verzeichnis — ein Fehler kann SSH-Keys oder ein Produktions-Repo überschreiben.
3. Stabilität & Audit: unklar, wo Logs liegen. Blinde Neuinstallationen löschen die einzigen Hinweise in ~/.openclaw/logs/errors.log; ohne Backups lässt sich die Konfiguration nach Upgrades nicht zurückrollen.

3. Vorbereitung vor der Installation: Mac- & Umgebungs-Checkliste

Ziel: Netzwerk-, Git- oder Speicherprobleme nicht mitten in der Installation entdecken. Bestehen: alle Punkte unten abgehakt, bevor das Installationsskript läuft.

• Betriebssystem: macOS 12+ (Intel oder Apple Silicon; Apple Silicon eignet sich besser für lokale Inferenz-Experimente, Cloud-Modelle folgen weiterhin der Anbieterdokumentation).
• Git: der offizielle Installer erwartet stabiles Netzwerk und ein Modellanbieter-Konto; git --version ≥ 2.30 empfohlen. Ohne Git: Xcode Command Line Tools oder brew install git installieren.
• Netzwerk: GitHub raw (Installationsskript) und die API Ihres LLM-Anbieters erreichbar; hinter Firmen-Proxies früh HTTPS_PROXY setzen.
• Speicher: der Installer kann Python 3.11, Node v22, ripgrep, ffmpeg und Repositories laden — ≥ 2 GB frei reservieren (mit Skills-Cache eher 1,5–3 GB; in der aktuellen Dokumentation bestätigen).
• Berechtigungen: persönliche Installation braucht kein sudo; Root-Installationen nutzen ggf. /root/.openclaw statt der Pfade unten.
• Backup: wenn ~/.openclaw existiert, zuerst cp -a ~/.openclaw ~/.openclaw.bak-$(date +%F) ausführen.
• Testverzeichnis: isolierter Workspace ~/openclaw-lab — nicht ~/Documents, Produktions-Git-Repos oder Geheimordner.

# Schneller Pre-Flight (als ein Block ausführen)
git --version
sw_vers
df -h ~
mkdir -p ~/openclaw-lab/{inbox,outbox,archive}
echo "OpenClaw lab sample: Q2 planning notes." > ~/openclaw-lab/inbox/sample.txt

Bei Fehlschlag: Git-Fehler → CLT/Homebrew; Speicher voll → Platz schaffen; Timeouts → Netzwerk/Proxy — nicht dreimal neu installieren, ohne Logs zu sichern.

4. Offizielle OpenClaw-Installation

Ziel: den gepflegten Installationseinstieg nutzen, damit install.sh Node und CLI übernimmt. Quelle: offizielle Installationsdokumentation (Versionsflags vor Veröffentlichung erneut prüfen).

4.1 Empfohlen: offizielles install.sh (macOS / Linux)

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

# Nur Installation, onboard später:
# curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard

Der Installer erkennt das System, installiert Node bei Bedarf (Dokumentation empfiehlt Node 24 oder Node 22.19+) und installiert die OpenClaw-CLI. Typische Pfade (zum Veröffentlichungszeitpunkt prüfen):

• Benutzerkonfiguration: ~/.openclaw/ (openclaw.json5, secrets/, State, Logs)
• Gateway-Standardport: 18789 (Control UI / WebSocket)
• macOS-Hintergrund: openclaw onboard --install-daemon registriert einen LaunchAgent

4.2 Initialisierung: onboard-Assistent

openclaw onboard --install-daemon

# Offizielle Verifikations-Trio:
openclaw --version
openclaw doctor
openclaw gateway status

Der Assistent führt durch Modellanbieter, API-Key und Gateway-Einrichtung. Niemals unbekannte Installationsskripte ausführen; niemals Keys in Git committen oder Screenshots in Chats posten.

4.3 Protokoll nach der Installation

source ~/.zshrc          # oder neues Terminal öffnen
openclaw --version         # Version für späteres Troubleshooting notieren
openclaw doctor            # Auto-Diagnose; --fix wenn angeboten

Bestehen: which openclaw findet den Befehl; openclaw doctor ohne blockierendes FAIL. Bei Fehlschlag zuerst: letzte 20 Zeilen des Installationslogs → PATH → Node unter Minimum oder npm-global bin fehlt in PATH.

Nicht sofort ~/.openclaw löschen bei Fehlschlag — Terminalausgabe und openclaw doctor zuerst sichern.

5. Modelle & API-Keys konfigurieren

Ziel: den OpenClaw-Agenten Ihr gewähltes LLM aufrufen lassen. Bestehen: nicht-interaktiver Smoke-Test liefert sinnvolle Antwort; openclaw auth list oder .env enthält den Eintrag, ohne Keys in der Shell-Historie.

5.1 Interaktive Einrichtung (erstes Mal)

openclaw onboard        # Modelle, Secrets, Gateway (mit --install-daemon kombinieren)
# Keys auch über auth-profiles / env — siehe offizielle Authentication-Docs

5.2 Umgebungsvariablen & Konfigurationsdateien

Hauptkonfiguration: ~/.openclaw/openclaw.json5; Secrets oft in ~/.openclaw/.env (bestätigen mit openclaw config path und openclaw config env-path). Beispiel — Variablennamen je nach Anbieter; keine veralteten Namen kopieren:

# Beispiel: OpenRouter (durch eigenen Key ersetzen; nie committen)
openclaw config set OPENROUTER_API_KEY "sk-or-v1-xxxxxxxx"

# Oder .env direkt bearbeiten (chmod 600 ~/.openclaw/.env)
echo 'OPENROUTER_API_KEY=sk-or-v1-xxxxxxxx' >> ~/.openclaw/.env

Grenze: Preise, Kontingente, regionale Verfügbarkeit und Datenschutzbedingungen ändern sich je nach Anbieter — aktuelle Bedingungen vor Produktion lesen. Dieser Artikel bindet Sie nicht an einen Modellnamen.

6. Workspace, Berechtigungen & Logs

Ziel: nach der Installation nachvollziehbar, begrenzt und rollback-freundlich sein. Prinzip: Least Privilege — zuerst nur das Testverzeichnis öffnen.

• Workspace: Sessions oder openclaw.json5 auf ~/openclaw-lab zeigen; AGENTS.md für Tool-Grenzen (siehe offizielle Context-Files-Docs).
• macOS-Berechtigungen: Datei-/Terminal-Tools können Full Disk Access anfordern — bei Erstabnahme lieber auf den Testordner beschränken, nicht die ganze Platte.
• Logs: Standard ~/.openclaw/logs/ (agent.log, errors.log, gateway.log). Nutzen: openclaw logs list, openclaw logs errors --since 30m.
• Secret-Hygiene: chmod 600 ~/.openclaw/.env; Backup-Zips nicht in Cloud-Laufwerke syncen; Agent-Zugriff auf ~/.ssh, Zahlungsdaten, Produktions-kubeconfig blockieren.
• Hintergrund (optional): für Telegram-/Discord-Gateways openclaw gateway setup und openclaw gateway install; Langzeitbetrieb in unserem OpenClaw-7×24-Gateway-Leitfaden.

Bestehen: nach Anweisung „nur ~/openclaw-lab lesen/schreiben“ werden Versuche außerhalb dieses Pfads verweigert oder protokolliert.

7. Dashboard öffnen & Gateway verifizieren (Port 18789)

Ziel: Control UI und WebSocket-Gateway bestätigen. Bestehen: http://127.0.0.1:18789 lädt; openclaw gateway status zeigt 18789 lauschend.

openclaw gateway status
openclaw dashboard
# Oder im Browser:
# http://127.0.0.1:18789/

# Remote-Mac (SSH-Forward — 18789 nicht ins öffentliche Internet stellen):
# ssh -L 18789:127.0.0.1:18789 user@remote-mac

# Portkonflikt:
lsof -i :18789
openclaw gateway restart
openclaw doctor --fix

Bei Fehlschlag zuerst: Port belegt → lsof; UI leer, Status OK → Cache/Proxy/WebSocket; Remote schlägt fehl → nur lokaler SSH-Tunnel. launchd: mit --install-daemon sollte nach Neustart openclaw gateway status laufen; sonst LaunchAgent-Logs und Benutzerkontext prüfen (siehe unseren Artikel zu launchd-Umgebungsvariablen).

8. Erstabnahme: Sieben-Schritte-Runbook

Diese sieben Schritte führen von „Konfiguration abgeschlossen“ zu „produktionsreif“ — wörtlich ausführen und Log-Ausschnitte sichern.

1. Diagnose: openclaw doctor --fix → kein unbehandeltes FAIL.
2. Modell-Ping: openclaw agent --message "Reply with exactly: OPENCLAW_OK" → Antwort enthält OPENCLAW_OK.
3. Datei lesen: Agent liest ~/openclaw-lab/inbox/sample.txt und zitiert die erste Zeile.
4. Datei schreiben: schreibt ~/openclaw-lab/outbox/ping.txt → mit cat sichtbar.
5. Logs: openclaw logs errors --since 10m → kein neuer unerklärlicher ERROR.
6. Neues Terminal: Fenster schließen, frisches öffnen, Schritt 2 wiederholen → PATH nicht nur session-spezifisch.
7. Optional Neustart: Schritt 2 nach Reboot wiederholen; bei installiertem Gateway zusätzlich openclaw gateway status.

Zitierbare Schwellen (persönliche Abnahme, kein offizielles SLA): Smoke-Antwort < 60 s; 0 unerklärliche ERROR in errors.log in 10 Minuten; neue Datei sichtbar unter ~/openclaw-lab/outbox.

9. Erster Praxisfall: Zusammenfassung + Todos + Rollback

Szenario: Beispieltext im Testverzeichnis lesen, kurze Zusammenfassung und drei Todos in Markdown erzeugen, Backup behalten — deckt Installation (CLI), Konfiguration (Modell) und Workflow (Lesen → Denken → Schreiben → Logs) ab.

# 1. Eingabe (überspringen, wenn Abschnitt 3 bereits erstellt hat)
cat > ~/openclaw-lab/inbox/weekly-notes.txt <<'EOF'
This week: drafted OpenClaw install doc.
Follow-up: set OpenRouter budget alert; evaluate Telegram gateway next week.
Risk: never commit API keys to git.
EOF

# 2. Interaktive Session
openclaw
# Beispiel-Prompt in der Session:
# "Use only ~/openclaw-lab. Read inbox/weekly-notes.txt,
#  write a summary under 150 words plus 3 todos to outbox/summary-and-todos.md,
#  and copy the source file to archive/weekly-notes.bak"

# 3. Nicht-interaktive Prüfung
ls -la ~/openclaw-lab/outbox/summary-and-todos.md
ls -la ~/openclaw-lab/archive/
openclaw logs agent -n 30 --since 15m

Bestehen:

• summary-and-todos.md enthält Zusammenfassung + 3 Todos passend zur Quelle.
• archive/ hat Backup; diff funktioniert.
• Logs zeigen Tool-Aufrufe; Anbieter-Dashboard zeigt den Aufruf (Kostenkontrolle).

Rollback: rm ~/openclaw-lab/outbox/summary-and-todos.md && cp ~/openclaw-lab/archive/weekly-notes.bak ~/openclaw-lab/inbox/weekly-notes.txt. Bei Fehlschlag zuerst: Kontextkürzung → Berechtigungen auf outbox → Tool-Fehler in errors.log.

10. Troubleshooting: schichtweise Fixes, keine blinde Neuinstallation

Fakten-Checkliste vor Veröffentlichung (Maintainer): install.sh-URL, minimales macOS, Standardpfade, CLI-Unterbefehle, Anbieter-Umgebungsvariablen, Log-Pfade — Dokumentation vor Release aktualisieren. Leser: bei Fehler openclaw doctor, dann errors.log; Neuinstallation erst zuletzt.

11. Nächste Schritte: Testverzeichnis → echter Workflow

Nach bestandener Abnahme in dieser Reihenfolge erweitern — nicht am ersten Tag Produktions-Repos oder Zahlungen anbinden:

1. Ein echtes Nebenprojekt-Verzeichnis freigeben; weiterhin ~/.ssh und globalen *-Zugriff blockieren.
2. openclaw cron für risikoarme Tagesaufgaben (z. B. Inventar eines Downloads-Ordners — weiter begrenzt).
3. Ein Messaging-Gateway (Telegram/Discord) mit Pairing, um Fremde zu blockieren (offizielle Security-Docs).
4. Wöchentlich openclaw backup --quick, dann Upgrade/Rollback aus Maintenance-Docs üben.