Fehlerbehebung15 Min. Lesezeit

OpenClaw Haeufige Fehler und wie man sie behebt

Umfassende Anleitung zur Diagnose und Behebung haeufiger OpenClaw-Fehler, einschliesslich Installationsproblemen, API-Fehlern, Kanalproblemen und Leistungsproblemen.

OpenClaw Guides

Tutorial Authors

2025-02-04

Schnelldiagnose

Bevor Sie sich mit spezifischen Fehlern befassen, fuehren Sie diese Diagnosen durch:

bash

# Gesamtstatus pruefen
openclaw status

# Konfiguration ueberpruefen
openclaw config validate

# Logs auf kuerzliche Fehler pruefen
openclaw logs --tail 50 --level error

# Gesundheitscheck durchfuehren
openclaw doctor

Installationsfehler

Fehler: "Node.js version too old"

Error: OpenClaw requires Node.js >= 22.0.0
Current version: 18.17.0

Loesung:

bash

# Mit nvm (empfohlen)
nvm install 22
nvm use 22
nvm alias default 22

# Oder mit Homebrew (macOS)
brew install node@22

# Ueberpruefen
node --version  # Sollte v22.x.x zeigen

Fehler: "EACCES permission denied"

npm ERR! Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules'

Loesung: Verwenden Sie nicht sudo. Beheben Sie stattdessen die npm-Berechtigungen:

bash

# Option 1: nvm verwenden (empfohlen)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Option 2: npm-Standardverzeichnis aendern
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# Dann neu installieren
npm install -g openclaw@latest

Fehler: "Cannot find module"

Error: Cannot find module '@openclaw/core'

Loesung:

bash

# npm-Cache loeschen und neu installieren
npm cache clean --force
npm uninstall -g openclaw
npm install -g openclaw@latest

# Oder das Installationsskript verwenden
curl -fsSL https://openclaw.ai/install.sh | bash

Fehler: "gyp ERR! build error" (Native Module)

gyp ERR! build error
gyp ERR! stack Error: `make` failed with exit code: 2

Loesung: Build-Tools installieren:

bash

# macOS
xcode-select --install

# Ubuntu/Debian
sudo apt install build-essential python3

# Windows
npm install -g windows-build-tools

API- und Authentifizierungsfehler

Fehler: "401 Unauthorized"

Error: API request failed with status 401: Invalid API key

Loesung:

bash

# Ueberpruefen Sie, ob Ihr API-Key gesetzt ist
openclaw config get api-key

# Falls leer oder falsch, erneut setzen
openclaw config set api-key

# Keyformat pruefen (Anthropic-Keys beginnen mit sk-ant-)
# Stellen Sie sicher, dass keine zusaetzlichen Leerzeichen oder Anfuehrungszeichen vorhanden sind

Fehler: "429 Rate Limited"

Error: Rate limit exceeded. Please retry after 60 seconds.

Loesung:

json

// ~/.openclaw/openclaw.json
{
  "model": {
    "rateLimiting": {
      "retryOnRateLimit": true,
      "maxRetries": 3,
      "retryDelay": 5000,
      "maxRequestsPerMinute": 30
    }
  }
}

Bei anhaltendem Rate Limiting erwaegen Sie ein Upgrade Ihrer API-Stufe oder die Verwendung eines anderen Modells:

bash

openclaw config set default-model claude-3-5-haiku

Fehler: "402 Payment Required"

Error: API request failed: Insufficient credits

Loesung:

Pruefen Sie Ihr API-Provider-Guthaben
Fuegen Sie Ihrem Konto Guthaben hinzu
Oder richten Sie Nutzungslimits ein:

json

// ~/.openclaw/openclaw.json
{
  "model": {
    "quotas": {
      "daily": {
        "enabled": true,
        "maxTokens": 100000,
        "warningThreshold": 80000
      }
    }
  }
}

Fehler: "Connection Refused" zur API

Error: connect ECONNREFUSED api.anthropic.com:443

Loesung:

bash

# Internetverbindung pruefen
ping api.anthropic.com

# Pruefen ob hinter einem Proxy
echo $HTTP_PROXY
echo $HTTPS_PROXY

# Proxy konfigurieren falls noetig
openclaw config set proxy http://your-proxy:8080

# Oder Firewall/VPN-Einstellungen pruefen

Gateway-Fehler

Fehler: "EADDRINUSE: Port already in use"

Error: listen EADDRINUSE: address already in use :::18789

Loesung:

bash

# Herausfinden, was den Port verwendet
lsof -i :18789

# Prozess beenden
kill -9 <PID>

# Oder einen anderen Port verwenden
openclaw gateway start --port 18790

# Konfiguration aktualisieren um neuen Port zu verwenden
openclaw config set gateway-port 18790

Fehler: "Gateway failed to start"

Error: Gateway failed to start: Cannot read config file

Loesung:

bash

# Konfigurationsdatei-Syntax validieren
openclaw config validate

# Falls beschaedigt, auf Standardwerte zuruecksetzen
openclaw config reset --confirm

# Dann neu konfigurieren
openclaw onboard

Fehler: "Gateway not responding"

bash

# Pruefen ob Gateway laeuft
openclaw status

# Falls gestoppt, pruefen warum
openclaw logs --tail 100

# Neustart versuchen
openclaw gateway restart

# Falls immer noch fehlschlaegt, Systemressourcen pruefen
free -h  # Speicher
df -h    # Speicherplatz

Kanalspezifische Fehler

WhatsApp: "Session expired"

Error: WhatsApp session invalid or expired

Loesung:

bash

# Erneut authentifizieren
openclaw channel disconnect whatsapp
openclaw channel connect whatsapp
# Neuen QR-Code scannen

WhatsApp: "QR code not generating"

bash

# Pruefen ob eine andere Sitzung aktiv ist
pkill -f "openclaw.*whatsapp"

# Alte Sitzungsdaten loeschen
rm -rf ~/.openclaw/whatsapp-session

# Erneut versuchen
openclaw channel connect whatsapp

Telegram: "Conflict: terminated by other getUpdates"

Error: Conflict: terminated by other getUpdates request

Eine andere Instanz verwendet denselben Bot-Token.

Loesung:

bash

# Alle OpenClaw-Instanzen stoppen
pkill -f openclaw

# Nach anderen laufenden Instanzen suchen
ps aux | grep openclaw

# Frisch starten
openclaw gateway start

Discord: "Invalid token"

Error: An invalid token was provided

Loesung:

bash

# Token im Discord Developer Portal regenerieren
# Bot → Reset Token

# OpenClaw aktualisieren
openclaw config set discord-token NEW_TOKEN
openclaw gateway restart

Discord: "Missing intents"

Error: Disallowed intents specified

Loesung:

Gehen Sie zum Discord Developer Portal
Waehlen Sie Ihre Anwendung → Bot
Aktivieren Sie die erforderlichen Intents unter "Privileged Gateway Intents"
Speichern und OpenClaw neu starten

Speicher- und Leistungsfehler

Fehler: "JavaScript heap out of memory"

FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed - JavaScript heap out of memory

Loesung:

bash

# Node.js Speicherlimit erhoehen
export NODE_OPTIONS="--max-old-space-size=4096"

# Zum Shell-Profil hinzufuegen fuer Persistenz
echo 'export NODE_OPTIONS="--max-old-space-size=4096"' >> ~/.bashrc

# OpenClaw neu starten
openclaw gateway restart

Fehler: "Too many open files"

Error: EMFILE: too many open files

Loesung:

bash

# Aktuelles Limit pruefen
ulimit -n

# Limit erhoehen (temporaer)
ulimit -n 65535

# Limit erhoehen (permanent - Linux)
echo "* soft nofile 65535" | sudo tee -a /etc/security/limits.conf
echo "* hard nofile 65535" | sudo tee -a /etc/security/limits.conf

# macOS
sudo launchctl limit maxfiles 65535 200000

Langsame Antwortzeiten

Diagnose:

bash

# Modell-Latenz pruefen
openclaw benchmark

# Systemressourcen pruefen
openclaw stats

Loesung:

json

// ~/.openclaw/openclaw.json
{
  "model": {
    "default": "claude-3-5-haiku",
    "streaming": true,
    "maxContextTokens": 4096
  },
  "gateway": {
    "caching": {
      "enabled": true,
      "ttl": 300
    }
  }
}

Konfigurationsfehler

Fehler: "Invalid YAML syntax"

Error: Config file has invalid YAML syntax at line 15

Loesung:

bash

# YAML validieren
openclaw config validate

# Haeufige Probleme:
# - Tabs statt Leerzeichen (verwenden Sie 2 Leerzeichen)
# - Fehlende Doppelpunkte nach Keys
# - Nicht zitierte Sonderzeichen

# Reparieren oder zuruecksetzen
openclaw config edit
# oder
openclaw config reset --confirm

Fehler: "Unknown configuration key"

Warning: Unknown configuration key 'gateway.unknownOption'

Loesung:

bash

# Verfuegbare Optionen pruefen
openclaw config list

# Unbekannte Keys entfernen
openclaw config edit

Fehler: "Environment variable not set"

Error: Required environment variable ANTHROPIC_API_KEY is not set

Loesung:

bash

# Zur .env-Datei hinzufuegen
echo "ANTHROPIC_API_KEY=sk-ant-xxxxx" >> ~/.openclaw/.env

# Oder in Shell exportieren
export ANTHROPIC_API_KEY=sk-ant-xxxxx

# Zum Shell-Profil hinzufuegen fuer Persistenz
echo 'export ANTHROPIC_API_KEY=sk-ant-xxxxx' >> ~/.bashrc

Datenbank- und Speicherfehler

Fehler: "Database locked"

Error: SQLITE_BUSY: database is locked

Loesung:

bash

# OpenClaw stoppen
openclaw gateway stop

# Nach Lock-Dateien suchen
ls -la ~/.openclaw/*.lock

# Veraltete Locks entfernen
rm ~/.openclaw/*.lock

# Neu starten
openclaw gateway start

Fehler: "Disk quota exceeded"

Error: ENOSPC: no space left on device

Loesung:

bash

# Speicherplatznutzung pruefen
df -h

# OpenClaw Logs und Cache loeschen
openclaw cache clear
openclaw logs clear --older-than 7d

# Alte Sitzungen loeschen
rm -rf ~/.openclaw/sessions/*.old

Weitere Hilfe erhalten

Debug-Logging aktivieren

bash

# Debug-Modus setzen
export OPENCLAW_DEBUG=true
openclaw gateway start

# Oder in der Konfiguration
openclaw config set logLevel debug

Diagnosebericht erstellen

bash

openclaw doctor --report > diagnostic-report.txt

Community-Support

Discord: discord.gg/openclaw
GitHub Issues: github.com/openclaw/openclaw/issues
Dokumentation: docs.openclaw.ai

Fehlerbericht einreichen

Beim Melden von Problemen bitte folgendes angeben:

bash

# Systeminfo
openclaw --version
node --version
uname -a

# Konfiguration (sensible Daten schwaerzen)
openclaw config show --redact

# Aktuelle Logs
openclaw logs --tail 100

Schnelldiagnose

Installationsfehler

Fehler: "Node.js version too old"

Fehler: "EACCES permission denied"

Fehler: "Cannot find module"

Fehler: "gyp ERR! build error" (Native Module)

API- und Authentifizierungsfehler

Fehler: "401 Unauthorized"

Fehler: "429 Rate Limited"

Fehler: "402 Payment Required"

Fehler: "Connection Refused" zur API

Gateway-Fehler

Fehler: "EADDRINUSE: Port already in use"

Fehler: "Gateway failed to start"

Fehler: "Gateway not responding"

Kanalspezifische Fehler

WhatsApp: "Session expired"

WhatsApp: "QR code not generating"

Telegram: "Conflict: terminated by other getUpdates"

Discord: "Invalid token"

Discord: "Missing intents"

Speicher- und Leistungsfehler

Fehler: "JavaScript heap out of memory"

Fehler: "Too many open files"

Langsame Antwortzeiten

Konfigurationsfehler

Fehler: "Invalid YAML syntax"

Fehler: "Unknown configuration key"

Fehler: "Environment variable not set"

Datenbank- und Speicherfehler

Fehler: "Database locked"

Fehler: "Disk quota exceeded"

Weitere Hilfe erhalten

Debug-Logging aktivieren

Diagnosebericht erstellen

Community-Support

Fehlerbericht einreichen

Naechste Schritte