Fallo de instalación npm durante actualización de OpenClaw en macOS - npm Install Failure During OpenClaw Upgrade on macOS

El instalador de OpenClaw informa de un fallo silencioso durante la fase de instalación global de npm. El script de instalación completa la detección del entorno correctamente pero falla al instalar el paquete sin exponer el error subyacente.

Comportamiento Observado:

  🦞 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

Indicadores Clave:

• La detección del entorno pasa (Node.js, npm, Git todos detectados)
• El comando de instalación se ejecuta pero devuelve un código de salida distinto de cero
• El archivo de registro existe pero el instalador trunca la salida
• Los intentos de reintento posteriores también fallan

Síntomas Secundarios Tras la Instalación Fallida:

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

El fallo de instalación se debe a una colisión entre la instalación preexistente de clawbot y el nuevo paquete openclaw. La instalación global de npm falla debido a una o más de las siguientes causas raíz:

1. Caché Obsoleta y Metadatos Conflictivos

Al actualizar desde clawbot a openclaw, npm puede retener entradas de caché corruptas o desactualizadas del paquete anterior. Los metadatos del registro npm para clawbot entran en conflicto con la resolución del nuevo paquete, causando fallos de resolución silenciosos.

Secuencia Técnica:

# 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. Conflictos de Permisos y Propiedad en macOS

El prefijo global de npm /usr/local/lib/node_modules requiere permisos de escritura elevados. En macOS con System Integrity Protection (SIP), combinado con instalaciones de Node gestionadas por Homebrew, frecuentemente ocurren conflictos de propiedad.

Configuración Problemática:

# 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. Conflicto del Gestor de Versiones de Node.js

El usuario tiene /usr/local/bin/node activo, que está fuera de las rutas típicas de los gestores de versiones de Node. Si nvm, fnm, o volta están instalados, pueden existir múltiples binarios de Node.js, causando que npm haga referencia a una instalación incorrecta o obsoleta.

4. Fallo de Compilación de Módulos Nativos (libvips/sharp)

El instalador usa SHARP_IGNORE_GLOBAL_LIBVIPS=1 para omitir libvips, pero si la instalación anterior de clawbot dejó artefactos del módulo sharp compilado, el proceso de reconstrucción de npm puede intentar recompilar código nativo incompatible.

Fase 1: Limpiar Caché de npm y Eliminar Instalación Anterior

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

Fase 2: Corregir Permisos del Prefijo Global de npm

# 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

Fase 3: Reinstalar 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

Fase 4: Método Alternativo (Node de Homebrew)

Si los problemas de permisos persisten, usa Node.js de Homebrew que gestiona los permisos automáticamente:

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

Antes vs. Después de la Configuración

Antes (Problemático):

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

Después (Correcto):

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

Después de aplicar la solución, verifica la instalación usando los siguientes comandos:

Verificación Básica

# 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

Verificación Avanzada

# 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

Salida Exitosa Esperada:

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

Verificación del Código de Salida:

# Verify clean exit code
$ echo $?
0

1. Múltiples Instalaciones de Node.js (Mac con Chip M)

Problema: Los Mac con Apple Silicon pueden tener Node.js instalado vía Homebrew (/opt/homebrew), nvm (~/.nvm), y descarga directa (/usr/local).

Detección:

# 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

Solución: Consolidar a una única instalación de Node.js. Eliminar rutas duplicadas de ~/.zshrc.

2. Directorios Protegidos por SIP en macOS

Problema: /usr/local puede estar parcialmente protegido bajo System Integrity Protection, causando fallos de permisos intermitentes.

Detección:

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

Solución: Usar exclusivamente el prefijo ~/.npm-global. Evitar sudo npm install -g ya que crea conflictos de propiedad.

3. Caché del Registro de npm Obsoleta

Problema: Las entradas de caché corruptas de la instalación anterior de clawbot persisten a pesar de la limpieza del caché.

Detección:

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

Solución:

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

4. Falta de Coincidencia de Arquitectura Intel vs. ARM

Problema: Instalar un paquete compilado para arquitectura Intel en Apple Silicon (o viceversa).

Detección:

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

Solución: Asegurarse de que npm descarga binarios nativos para la arquitectura correcta. Usar npm rebuild si es necesario.

5. Conflictos de Configuración de .npmrc

Problema: Los archivos .npmrc a nivel de proyecto o global anulan el comportamiento esperado.

Detección:

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

Solución: Eliminar o corregir entradas conflictivas de .npmrc. Priorizar ~/.npmrc sobre la configuración a nivel de proyecto.