[npm Installationsfehler bei OpenClaw-Upgrade auf macOS] - npm Install Failure During OpenClaw Upgrade on macOS

Der OpenClaw-Installer meldet einen stillen Fehler während der npm global install-Phase. Das Installationsskript führt die Umgebungserkennung erfolgreich durch, scheitert jedoch daran, das Paket zu installieren, ohne den zugrunde liegenden Fehler offenzulegen.

Beobachtetes Verhalten:

  🦞 OpenClaw Installer
  The only crab in your contacts you actually want to hear from. 🦞

✓ Detected: macos

Install plan
OS: macos
Install method: npm
Requested version: latest

[1/3] Preparing environment
✓ Homebrew already installed
✓ Node.js v22.22.0 found
· Active Node.js: v22.22.0 (/usr/local/bin/node)
· Active npm: 10.9.4 (/usr/local/bin/npm)

[2/3] Installing OpenClaw
✓ Git already installed
· Installing OpenClaw v2026.2.26
! npm install failed for openclaw@latest
  Command: env SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm --loglevel error --silent --no-fund --no-audit install -g openclaw@latest
  Installer log: /var/folders/mm/rhtrkglj0cn_h1xhmkp21w540000gn/T/tmp.kWd5ANRq99
! npm install failed; showing last log lines
! npm install failed; retrying

Wichtige Indikatoren:

• Umgebungserkennung erfolgreich (Node.js, npm, Git alle erkannt)
• Installationsbefehl wird ausgeführt, gibt aber Exit-Code ungleich Null zurück
• Log-Datei existiert, aber Installer kürzt die Ausgabe
• Nachfolgende Wiederholungsversuche scheitern ebenfalls

Sekundäre Symptome nach fehlgeschlagener Installation:

# Verify installation state
$ openclaw --version
zsh: command not found: openclaw

# Check npm global packages
$ npm list -g --depth=0 | grep openclaw
# (leere Ausgabe - Paket nicht installiert)

Der Installationsfehler resultiert aus einer Kollision zwischen der bereits vorhandenen clawbot-Installation und dem neuen openclaw-Paket. Die npm global install schlägt aufgrund eines oder mehrerer der folgenden Ursachen fehl:

1. Veralteter Cache und widersprüchliche Metadaten

Bei einem Upgrade von clawbot zu openclaw kann npm beschädigte oder veraltete Cache-Einträge für das vorherige Paket beibehalten. Die npm-Registry-Metadaten für clawbot stehen in Konflikt mit der neuen Paketauflösung, was zu stillen Auflösungsfehlern führt.

Technische Sequenz:

# Internal npm behavior during upgrade
npm install -g openclaw@latest
  → Check registry for "openclaw"
  → npm cache contains stale "clawbot" metadata
  → Version resolution returns incorrect package or 404
  → Exit code: 1 (silently truncated by --silent flag)

2. Berechtigungs- und Besitzkonflikte unter macOS

Das npm global prefix /usr/local/lib/node_modules erfordert erhöhte Schreibrechte. Unter macOS mit System Integrity Protection (SIP) in Kombination mit Homebrew-verwalteten Node-Installationen treten häufig Besitzkonflikte auf.

Problematische Konfiguration:

# Typical macOS permission issue
$ ls -la /usr/local/lib/node_modules
drwxr-xr-x  root            admin  # Owned by root
drwxr-xr-x  user           staff  # Previous installation owned by user

# npm install cannot write to root-owned directories

3. Node.js-Versionsmanager-Konflikt

Der Benutzer hat /usr/local/bin/node aktiv, was sich außerhalb typischer Node-Versionsmanager-Pfade befindet. Wenn nvm, fnm oder volta installiert sind, können mehrere Node.js-Binärdateien existieren, was dazu führt, dass npm auf eine falsche oder veraltete Installation verweist.

4. Native Modul-Kompilierungsfehler (libvips/sharp)

Der Installer verwendet SHARP_IGNORE_GLOBAL_LIBVIPS=1, um libvips zu überspringen, aber wenn die vorherige clawbot-Installation kompilierte sharp-Modul-Artefakte hinterlassen hat, kann npm’s Rebuild-Prozess versuchen, inkompatiblen nativen Code neu zu kompilieren.

Phase 1: npm-Cache bereinigen und vorherige Installation entfernen

# Step 1: Clear npm cache completely
npm cache clean --force

# Step 2: Remove previous clawbot installation
npm uninstall -g clawbot

# Step 3: Verify removal
npm list -g --depth=0 | grep -E "(clawbot|openclaw)" || echo "No previous installations found"

Phase 2: npm Global Prefix-Berechtigungen korrigieren

# Step 4: Create npm global directory with correct permissions
mkdir -p ~/.npm-global

# Step 5: Configure npm to use local prefix
npm config set prefix '~/.npm-global'

# Step 6: Add to PATH (add to ~/.zshrc for persistent effect)
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
export PATH=~/.npm-global/bin:$PATH

# Step 7: Verify npm prefix configuration
npm config get prefix
# Expected output: /Users/[username]/.npm-global

Phase 3: OpenClaw neu installieren

# Step 8: Install OpenClaw with verbose logging for debugging
npm install -g openclaw@latest --loglevel verbose

# Alternative: If specific version required
npm install -g [email protected] --loglevel verbose

Phase 4: Alternative Methode (Homebrew Node)

Wenn Berechtigungsprobleme weiterhin bestehen, verwenden Sie Homebrew’s Node.js, das Berechtigungen automatisch handhabt:

# Step 9: Install Node.js via Homebrew (if not already)
brew install node

# Step 10: Reinstall OpenClaw with Homebrew-managed Node
npm install -g openclaw@latest

# Step 11: Verify installation path
which openclaw
# Expected: /opt/homebrew/bin/openclaw (M1/M2) or /usr/local/bin/openclaw (Intel)

Vorher vs. Nachher Konfiguration

Vorher (Problematisch):

# ~/.npmrc or global npm config
prefix=/usr/local  # Root-owned, requires sudo
cache=/var/root/.npm  # Inaccessible

# Environment
NODE_PATH=/usr/local/lib/node_modules
PATH=/usr/local/bin:$PATH

Nachher (Korrekt):

# ~/.npmrc or global npm config
prefix=/Users/[username]/.npm-global
cache=/Users/[username]/.npm
node_options=--max-old-space-size=4096

# Environment (in ~/.zshrc)
export PATH=~/.npm-global/bin:$PATH
export NPM_CONFIG_PREFIX=~/.npm-global

Nachdem Sie die Lösung angewendet haben, verifizieren Sie die Installation mit den folgenden Befehlen:

Grundlegende Verifizierung

# Test 1: Check OpenClaw binary is accessible
$ openclaw --version
v2026.2.26

# Test 2: Verify npm global package status
$ npm list -g --depth=0 | grep openclaw
├── [email protected]

# Test 3: Confirm installation location
$ npm list -g --depth=0 --parseable | grep openclaw
/Users/[username]/.npm-global/lib/node_modules/openclaw

# Test 4: Test OpenClaw initialization
$ openclaw init
# Should display setup wizard without errors

Erweiterte Verifizierung

# Test 5: Verify all dependencies are intact
$ openclaw doctor
✓ Node.js version: v22.22.0
✓ npm version: 10.9.4
✓ OpenClaw installation: valid
✓ Configuration directory: accessible
✓ Plugin directory: accessible

# Test 6: Check for conflicting installations
$ which -a openclaw
/Users/[username]/.npm-global/bin/openclaw
# Should show only one path

Erwartete erfolgreiche Ausgabe:

✓ OpenClaw v2026.2.26 installed successfully
✓ Binary location: /Users/[username]/.npm-global/bin/openclaw
✓ All dependencies resolved
✓ Installation complete

Exit-Code-Verifizierung:

# Verify clean exit code
$ echo $?
0

1. Mehrere Node.js-Installationen (M-Serie Macs)

Problem: Apple Silicon Macs haben möglicherweise Node.js über Homebrew (/opt/homebrew), nvm (~/.nvm) und direkten Download (/usr/local) installiert.

Erkennung:

# Check for multiple Node installations
$ which -a node
/opt/homebrew/bin/node
/usr/local/bin/node

# Check actual symlink targets
$ ls -la /usr/local/bin/node
/usr/local/bin/node -> ../Cellar/node/.../bin/node  # Homebrew Intel
$ ls -la /opt/homebrew/bin/node
/opt/homebrew/bin/node -> ../opt/node/bin/node  # Homebrew ARM

Lösung: Konsolidieren Sie auf eine einzelne Node.js-Installation. Entfernen Sie doppelte Pfade aus ~/.zshrc.

2. SIP-geschützte Verzeichnisse unter macOS

Problem: /usr/local kann unter System Integrity Protection teilweise geschützt sein, was zu intermittierenden Berechtigungsfehlern führt.

Erkennung:

$ ls -la /usr/local/lib/node_modules
ls: cannot access '/usr/local/lib/node_modules': Operation not permitted

Lösung: Verwenden Sie ausschließlich ~/.npm-global als Präfix. Vermeiden Sie sudo npm install -g, da dies Besitzkonflikte erstellt.

3. Veralteter npm Registry-Cache

Problem: Beschädigte Cache-Einträge von vorheriger clawbot-Installation bleiben trotz Cache-Bereinigung bestehen.

Erkennung:

# Check cache integrity
$ npm cache verify
npm warn Failed to clean up old cache
npm error Unexpected end of JSON input while parsing near '...": "1.0.0", "dependencies": {'

Lösung:

# Force complete cache deletion
rm -rf ~/.npm
npm cache clean --force --cache ~/.npm

4. Intel vs. ARM-Architektur-Mismatch

Problem: Installation eines für Intel-Architektur kompilierten Pakets auf Apple Silicon (oder umgekehrt).

Erkennung:

$ file $(which openclaw)
# Intel: Mach-O 64-bit executable x86_64
# ARM:   Mach-O 64-bit executable arm64

Lösung: Stellen Sie sicher, dass npm native Binärdateien für die richtige Architektur herunterlädt. Verwenden Sie bei Bedarf npm rebuild.

5. .npmrc-Konfigurationskonflikte

Problem: Projektbezogene oder globale .npmrc-Dateien überschreiben das erwartete Verhalten.

Erkennung:

# Check all .npmrc files
$ cat ~/.npmrc
prefix=~/.npm-global
$ cat ./.npmrc  # in current directory
prefix=/usr/local  # Conflicts!

Lösung: Entfernen oder korrigieren Sie widersprüchliche .npmrc-Einträge. Priorisieren Sie ~/.npmrc gegenüber projektbezogener Konfiguration.