OpenClaw Fehlerbehebung

Was dieser Artikel über OpenClaw-Fehlerbehebung behandelt

Häufige Fehler nach der Installation.
Probleme mit dem Gateway, Providern und Modellen.
Ollama-Verbindungsfehler und falsche Endpunkte.
Berechtigungen, Netzwerk und Sicherheit.
Werkzeuge wie openclaw doctor und openclaw security audit.

Einleitung: OpenClaw Fehlerbehebung

OpenClaw ist ein mächtiges Werkzeug, das tiefen Zugriff auf das System erhält. Bei der Installation und dem Betrieb können daher verschiedene Probleme auftreten: fehlende API-Keys, falsche Endpunkte, Berechtigungsfehler oder ein nicht erreichbares Gateway. Wer die häufigsten Fehlerquellen kennt, kann sie schnell eingrenzen und beheben.

Dieser Artikel bietet einen systematischen Ansatz zur Fehlersuche bei OpenClaw auf Proxmox oder anderen Linux-Systemen.

Grundlegendes Vorgehen

Version prüfen: openclaw --version
Doctor laufen lassen: openclaw doctor
Konfiguration ansehen: openclaw config list
Logs lesen: ~/.openclaw/logs/ oder stderr
Minimaltest: Ein einzelnes Modell und ein einfacher Prompt.
Schrittweise erweitern: Provider, Gateway, Skills, Tools.

Installationsfehler

Installation bricht ab

Prüfe die Node.js-Version. OpenClaw benötigt eine aktuelle Version.
Nutze den offiziellen Installer:

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash

Stelle sicher, dass npm und curl verfügbar sind.
Prüfe Internetverbindung und DNS-Auflösung.

Befehl nicht gefunden

Wenn openclaw nach der Installation nicht verfügbar ist:

which openclaw
/usr/bin/openclaw

Falls nicht im Pfad:

export PATH="$PATH:/usr/bin"

Onboarding-Probleme

Wizard startet nicht

openclaw onboard --classic

Falls interaktive Ausgaben fehlen, prüfe das Terminal und ob stdin verfügbar ist.

Provider wird nicht erkannt

Während des Onboardings wurde möglicherweise Skip for now gewählt. Rufe das Onboarding erneut auf oder konfiguriere den Provider manuell:

openclaw config set models.providers.anthropic.apiKey "DEIN_ANTHROPIC_API_KEY"

Gateway-Fehler

Gateway ist nicht erreichbar

openclaw gateway install
openclaw gateway status

Falls das Gateway nicht läuft, prüfe:

Läuft der Prozess?
Ist der Port belegt?
Wurde der richtige Bind-Parameter genutzt?

Gateway an öffentlicher Schnittstelle

Das ist ein Sicherheitsrisiko. Passe die Konfiguration an:

openclaw config set gateway.bind "127.0.0.1"

Für externen Zugriff über Tailscale oder SSH-Tunnel dennoch keine 0.0.0.0-Bindung verwenden.

Provider- und Modellfehler

Modell wird nicht gefunden

openclaw models list --provider anthropic
openclaw models list --provider ollama

Prüfe, ob der richtige Provider konfiguriert ist.
Prüfe, ob das Modell bei Ollama heruntergeladen wurde.
Modellnamen müssen exakt passen, einschließlich Tag.

Claude API Key ungültig

Stelle sicher, dass der Key im richtigen Format vorliegt.
Prüfe, ob Guthaben oder Limits überschritten wurden.
Setze den Key neu:

export ANTHROPIC_API_KEY="NEUER_KEY"
openclaw config set models.providers.anthropic.apiKey "$ANTHROPIC_API_KEY"

Ollama-Verbindungsfehler

Falscher Endpunkt

OpenClaw nutzt den nativen Ollama-Endpoint:

http://127.0.0.1:11434

Nicht:

http://127.0.0.1:11434/v1

openclaw config set models.providers.ollama.baseUrl "http://127.0.0.1:11434"
openclaw config set models.providers.ollama.apiKey "ollama-local"

Ollama nicht erreichbar

curl http://127.0.0.1:11434/api/tags

Wenn das fehlschlägt, prüfe:

Läuft Ollama?
Ist der Port korrekt?
Firewall oder Netzwerkisolation blockiert?
In einem LXC ist das TUN-Device nicht nötig, aber Ollama muss gestartet sein.

Modell passt nicht in den Speicher

Ollama bricht ab oder antwortet sehr langsam.
Prüfe RAM/VRAM mit free -h oder nvidia-smi.
Wähle ein kleineres Modell oder eine stärkere Quantisierung.

Berechtigungsfehler

OpenClaw läuft als root

OpenClaw sollte unter einem dedizierten Benutzer laufen:

useradd -m -s /bin/bash openclaw
mv /root/.openclaw /home/openclaw/.openclaw
chown -R openclaw:openclaw /home/openclaw/.openclaw

Dateien nicht lesbar

ls -la /home/openclaw/.openclaw

Berechtigungen sollten auf den OpenClaw-Benutzer gehören.

Netzwerk- und Firewall-Probleme

Kein Internetzugriff: Für Installationen und manche Skills notwendig.
Proxmox Firewall blockiert Ports: Nur notwendige Ports zwischen LXC erlauben.
Tailscale nicht erreichbar: Prüfe, ob der Node online ist.
Gateway nicht extern erreichbar: Gewollt, wenn an loopback gebunden.

Sicherheitsprüfungen

openclaw security audit --deep
openclaw doctor --fix

security audit zeigt Risiken wie unsichere Berechtigungen, offene Gateways oder veraltete Komponenten. doctor prüft den Gesundheitszustand der Installation und kann einige Probleme automatisch beheben.

Typische Fehlermeldungen

`ECONNREFUSED`

Der Zieldienst ist nicht erreichbar. Prüfe Host, Port und Firewall.

`Unauthorized`

API-Key fehlt oder ist ungültig. Provider-Einstellungen prüfen.

`Model not found`

Modellname falsch oder Modell nicht installiert. openclaw models list nutzen.

`Permission denied`

Berechtigungsproblem beim Dateisystem. Benutzer und Rechte prüfen.

`Cannot find module`

Installation eventuell unvollständig. Neuinstallation oder openclaw doctor prüfen.

Weiterführende Links und Infos

FAQ: OpenClaw Fehlerbehebung

Wie starte ich OpenClaw neu? Beende das Gateway und starte es erneut, oder starte den ganzen LXC neu.

Wo sind die OpenClaw-Logs? Meist unter ~/.openclaw/logs/, alternativ Ausgabe des Prozesses.

Wie prüfe ich die Konfiguration? Mit openclaw config list oder openclaw doctor.

Was tun bei ECONNREFUSED? Zielhost und Port prüfen, Dienst starten, Firewall freigeben.

Sollte OpenClaw als root laufen? Nein, ein dedizierter Benutzer ist sicherer.

Quellen und weiterführende Literatur

OpenClaw: https://openclaw.ai/
Ollama Docs: https://github.com/ollama/ollama/blob/main/docs/
Proxmox Troubleshooting: https://pve.proxmox.com/wiki/Troubleshooting

Zusammenfassung: OpenClaw Fehlerbehebung

OpenClaw-Fehler lassen sich meist auf Installationsprobleme, falsche Provider-Einstellungen, Netzwerkfehler oder Berechtigungen eingrenzen. openclaw doctor und openclaw security audit helfen bei der Diagnose. Wichtig sind ein dedizierter Benutzer, loopback-gebundenes Gateway, korrekter Ollama-Endpunkt und regelmäßige Sicherheitsprüfungen. Wer schrittweise vorgeht und die Logs beachtet, findet die meisten Probleme schnell.

Täglicher Artikel