npm Install Failure During OpenClaw Upgrade on macOS

The OpenClaw installer reports a silent failure during the npm global install phase. The installation script completes environment detection successfully but fails to install the package without exposing the underlying error.

Observed Behavior:

  🦞 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

Key Indicators:

• Environment detection passes (Node.js, npm, Git all detected)
• Install command executes but returns non-zero exit code
• Log file exists but installer truncates output
• Subsequent retry attempts also fail

Secondary Symptoms After Failed Installation:

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

# Check npm global packages
$ npm list -g --depth=0 | grep openclaw
# (empty output - package not installed)

The installation failure stems from a collision between the pre-existing clawbot installation and the new openclaw package. The npm global install fails due to one or more of the following root causes:

1. Stale Cache and Conflicting Metadata

When upgrading from clawbot to openclaw, npm may retain corrupted or outdated cache entries for the previous package. The npm registry metadata for clawbot conflicts with the new package resolution, causing silent resolution failures.

Technical Sequence:

# 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. Permission and Ownership Conflicts on macOS

The npm global prefix /usr/local/lib/node_modules requires elevated write permissions. On macOS with System Integrity Protection (SIP), combined with Homebrew-managed Node installations, ownership conflicts frequently occur.

Problematic Configuration:

# 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 Version Manager Conflict

The user has /usr/local/bin/node active, which is outside typical Node version manager paths. If nvm, fnm, or volta are installed, multiple Node.js binaries may exist, causing npm to reference an incorrect or stale installation.

4. Native Module Compilation Failure (libvips/sharp)

The installer uses SHARP_IGNORE_GLOBAL_LIBVIPS=1 to skip libvips, but if the previous clawbot installation left compiled sharp module artifacts, npm’s rebuild process may attempt to recompile incompatible native code.

Phase 1: Clean npm Cache and Remove Previous Installation

# 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: Fix npm Global Prefix Permissions

# 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: Reinstall OpenClaw

# 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 Method (Homebrew Node)

If permission issues persist, use Homebrew’s Node.js which handles permissions automatically:

# 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)

Before vs. After Configuration

Before (Problematic):

# ~/.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

After (Correct):

# ~/.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

After applying the fix, verify the installation using the following commands:

Basic Verification

# 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

Advanced Verification

# 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

Expected Successful Output:

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

Exit Code Verification:

# Verify clean exit code
$ echo $?
0

1. Multiple Node.js Installations (M-Series Macs)

Problem: Apple Silicon Macs may have Node.js installed via Homebrew (/opt/homebrew), nvm (~/.nvm), and direct download (/usr/local).

Detection:

# 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

Solution: Consolidate to a single Node.js installation. Remove duplicate paths from ~/.zshrc.

2. SIP-Protected Directories on macOS

Problem: /usr/local may be partially protected under System Integrity Protection, causing intermittent permission failures.

Detection:

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

Solution: Use ~/.npm-global prefix exclusively. Avoid sudo npm install -g as it creates ownership conflicts.

3. Stale npm Registry Cache

Problem: Corrupted cache entries from previous clawbot installation persist despite cache clean.

Detection:

# 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": {'

Solution:

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

4. Intel vs. ARM Architecture Mismatch

Problem: Installing a package compiled for Intel architecture on Apple Silicon (or vice versa).

Detection:

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

Solution: Ensure npm downloads native binaries for the correct architecture. Use npm rebuild if necessary.

5. .npmrc Configuration Conflicts

Problem: Project-level or global .npmrc files override expected behavior.

Detection:

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

Solution: Remove or correct conflicting .npmrc entries. Prioritize ~/.npmrc over project-level configuration.