La instalación de OpenClaw falla con error de memoria insuficiente - OpenClaw 2026.3.2 Installation Fails with Out-of-Memory Error on Low-RAM Systems

Manifestación principal

El proceso de instalación recibe una señal SIGKILL (código de salida 137) durante la fase de instalación de npm, específicamente cuando se compilan las dependencias nativas del módulo de procesamiento de imágenes sharp.

main: line 638:  4915 Killed                  "${cmd[@]}" > "$log" 2>&1
! npm install failed for openclaw@latest

Estado de los recursos del sistema durante el fallo

$ free -h
               total        used        free      shared  buff/cache   available
Mem:           1.9Gi       1.7Gi       165Mi       3.0Mi       278Mi       262Mi
Swap:          2.0Gi       840Mi       1.2Gi

Progresión del error

1. El instalador entra en la fase [2/3] Installing OpenClaw
2. npm comienza npm install -g openclaw@latest
3. El proceso consume la memoria disponible rápidamente
4. El OOM killer de Linux termina el proceso con SIGKILL
5. El instalador reintenta dos veces, luego falla con la ruta del registro del instalador

Códigos de salida observados

• 137 — Proceso terminado por SIGKILL (Fuera de memoria)
• 1 — Código de salida de fallo de instalación de npm

Contexto del entorno

• Proveedor: Droplet de DigitalOcean
• SO: Ubuntu 24.04
• Node.js: v22.22.0
• npm: 10.9.4
• Memoria: 1.9GB total

Causa principal: Consumo de memoria de la biblioteca Sharp

El módulo sharp (una biblioteca de procesamiento de imágenes de alto rendimiento utilizada por OpenClaw para la generación de miniaturas y transformaciones de imágenes) requiere una cantidad considerable de memoria durante sus fases de compilación nativa y ejecución inicial. En OpenClaw v2026.3.2, la cadena de dependencias ahora requiere sharp, donde anteriormente no lo hacía, o la versión de sharp aumentó su consumo de memoria.

Secuencia técnica del fallo

1. Resolución de dependencias: npm resuelve [email protected] que incluye sharp como dependencia transitiva
2. Compilación nativa: npm intenta compilar los enlaces nativos VIPS de sharp
3. Escalada de memoria: El proceso de compilación genera procesos de trabajo paralelos, cada uno consumiendo memoria
4. Agotamiento de memoria: La memoria combinada de Node.js, npm y los procesos de compilación excede los 2GB disponibles
5. Disparador OOM: El kernel de Linux invoca al OOM killer para reclamar memoria para procesos críticos del sistema

Factores arquitectónicos

• Paralelismo de npm: npm v10.x utiliza instalación paralela por defecto, generando múltiples procesos concurrentes
• Compilación de Sharp: El módulo sharp requiere compilar código C++ nativo contra libvips, una operación que consume mucha memoria
• Introducción de regresión: La versión 2026.3.2 introdujo una nueva dependencia de sharp o actualizó a una versión de sharp con mayores requisitos de memoria en comparación con v2026.3.1

Análisis del presupuesto de memoria

+------------------+---------------+
| Component        | Est. Memory   |
+------------------+---------------+
| System baseline  | ~700MB        |
| Node.js runtime  | ~200MB        |
| npm process      | ~150MB        |
| Sharp compile x4 | ~200MB each   |
| Compilation temp | ~300MB        |
+------------------+---------------+
| Total required   | ~2.1GB+       |
| Available        | 1.9GB         |
+------------------+---------------+

Por qué 2GB es el umbral

El sistema requiere memoria para buffers del kernel, procesos del espacio de usuario y la tubería de compilación simultáneamente. El déficit de ~200MB entre la memoria requerida y la disponible desencadena la condición OOM de manera determinista en sistemas con exactamente 2GB de RAM.

Solución 1: Agregar espacio de intercambio (Recomendado para corrección persistente)

Esta solución crea espacio de intercambio persistente que sobrevive a los reinicios.

# Step 1: Create a 2GB swap file
fallocate -l 2G /swapfile

# Step 2: Set secure permissions (root-only access)
chmod 600 /swapfile

# Step 3: Format as swap space
mkswap /swapfile

# Step 4: Activate the swap file
swapon /swapfile

# Step 5: Verify swap is active
swapon --show

# Step 6: Add to /etc/fstab for persistence across reboots
echo '/swapfile none swap sw 0 0' >> /etc/fstab

Antes vs Después:

# BEFORE: No swap, installation fails
$ free -h | grep Swap
Swap:             0B

# AFTER: 2GB swap available
$ free -h | grep Swap
Swap:          2.0Gi       0B       2.0Gi

Solución 2: Limitar el paralelismo de npm durante la instalación

Reducir los trabajadores de instalación paralelos de npm para disminuir el consumo máximo de memoria.

# Option A: Set npm jobs limit via environment variable
env NPM_CONFIG_JOBS=1 npm --loglevel error --silent --no-fund --no-audit install -g openclaw@latest

# Option B: Use npm ci with reduced parallelism
npm config set maxsockets 1
npm install -g openclaw@latest

Configuración de variables de entorno:

# Add to shell profile for persistent effect
echo 'export NPM_CONFIG_JOBS=1' >> ~/.bashrc
source ~/.bashrc

Solución 3: Usar el indicador SHARP_IGNORE_GLOBAL_LIBVIPS con memoria reducida

El instalador ya establece SHARP_IGNORE_GLOBAL_LIBVIPS=1, pero puedes agregar restricciones de memoria.

# Set VIPS memory cache limit before installation
export VIPS_CONCURRENCY=1
export VIPS_DISC_THRESHOLD=100

# Then run the installer
curl -fsSL https://openclaw.ai/install.sh | bash

Solución 4: Actualizar a una instancia más grande (Corrección de infraestructura)

Para entornos de producción, migra a una instancia con ≥4GB de RAM:

# DigitalOcean example: resize droplet
doctl compute droplet-action resize <DROPLET_ID> --size s-2vcpu-4gb

# Or use the control panel: Droplet → Resize → Select 4GB plan

Solución 5: Instalación Docker con omisión de límite de memoria

Si usas Docker, asegúrate de tener una asignación de memoria adecuada y usa la imagen oficial.

# Docker Desktop: Settings → Resources → Memory: 4GB minimum

# Pull the official image (handles dependencies internally)
docker pull openclaw/openclaw:latest

# Run with proper memory allocation
docker run -d \
  --memory="2g" \
  --memory-swap="4g" \
  --name openclaw \
  openclaw/openclaw:latest

Corrección combinada multinivel (Más robusta)

#!/bin/bash
# combined-fix.sh - Comprehensive low-memory installation script

set -e

echo "=== Low-Memory OpenClaw Installation Fix ==="

# 1. Ensure swap exists
if ! swapon --show | grep -q /swapfile; then
    echo "[1/4] Creating swap file..."
    fallocate -l 2G /swapfile || dd if=/dev/zero of=/swapfile bs=1M count=2048
    chmod 600 /swapfile
    mkswap /swapfile
    swapon /swapfile
    echo '/swapfile none swap sw 0 0' >> /etc/fstab
fi

# 2. Configure memory limits for sharp
echo "[2/4] Configuring memory limits..."
export SHARP_IGNORE_GLOBAL_LIBVIPS=1
export VIPS_CONCURRENCY=1

# 3. Limit npm parallelism
echo "[3/4] Limiting npm parallelism..."
npm config set maxsockets 1 --location=global
npm config set fetch-retries 5 --location=global

# 4. Install OpenClaw
echo "[4/4] Installing OpenClaw..."
curl -fsSL https://openclaw.ai/install.sh | bash

echo "=== Installation complete ==="

Pasos de verificación posterior a la corrección

Paso 1: Confirmar que el swap está activo

$ swapon --show
NAME      TYPE      SIZE   USED PRIO
/swapfile file        2G     0B   -2

$ free -h
               total        used        free      shared  buff/cache   available
Mem:           1.9Gi       1.5Gi       123Mi       2.0Mi       315Mi       289Mi
Swap:          2.0Gi         0Bi       2.0Gi

Paso 2: Verificar la instalación de OpenClaw

$ openclaw --version
openclaw v2026.3.2

$ which openclaw
/usr/local/bin/openclaw

Paso 3: Probar el inicio de OpenClaw

$ openclaw status
✓ OpenClaw gateway responding
✓ Memory usage within limits
✓ All services operational

Paso 4: Verificar fugas de memoria bajo carga

$ openclaw status --verbose
Node.js: v22.22.0
OpenClaw: v2026.3.2
Memory: RSS 285MB / 2048MB limit
Sharp: Initialized (concurrency: 1)
Uptime: 0h 0m 12s

Paso 5: Verificar la funcionalidad del módulo Sharp

$ openclaw diagnostic --module=sharp
[sharp] Module loaded: v0.33.5
[sharp] VIPS_DISC_THRESHOLD: 100MB
[sharp] VIPS_CONCURRENCY: 1
[sharp] Memory cache: 50MB
[sharp] ✓ Allocated worker pool (1 worker)
[sharp] ✓ Thumbnail pipeline operational

Paso 6: Confirmar que el registro de instalación no muestra errores

$ cat /tmp/openclaw-install-*.log | grep -E "(success|complete|installed|error|failed)" | tail -20
[2/3] Installing OpenClaw
✓ Installing OpenClaw v2026.3.2
✓ npm install completed successfully
✓ Binary linked to /usr/local/bin/openclaw
✓ Installation complete

Código de salida esperado al reintentar (si el swap era el único problema)

$ echo $?
0

1. Archivo de swap no persiste después del reinicio

Problema: El swap se pierde después del reinicio del sistema en algunas configuraciones.

Solución: Verificar la entrada en /etc/fstab:

# CORRECT entry in /etc/fstab
/swapfile none swap sw 0 0

# Verify it exists
grep swapfile /etc/fstab

2. Límites de memoria del contenedor Docker

Problema: Docker Desktop/Engine aplica límites de memoria que son independientes del host.

Solución: Aumentar la asignación de memoria de Docker:

# Docker Desktop (GUI)
# Settings → Resources → Memory: Set to 4GB or higher

# Docker Engine (daemon.json)
# Add to /etc/docker/daemon.json:
{
  "default-ulimits": {
    "memlock": {
      "Name": "memlock",
      "Soft": -1,
      "Hard": -1
    }
  }
}

3. Alcance incorrecto de SHARP_IGNORE_GLOBAL_LIBVIPS

Problema: Establecer SHARP_IGNORE_GLOBAL_LIBVIPS=1 afecta el comportamiento en tiempo de ejecución, no la compilación de instalación.

Solución: Usar NPM_CONFIG_JOBS o npm config set maxsockets para la fase de instalación.

4. Proveedores VPS con swap deshabilitado

Problema: Algunos proveedores en la nube (por ejemplo, ciertos droplets de DO) tienen el swap deshabilitado por defecto.

Solución: Verificar con:

$ cat /proc/swaps
Filename                                Type            Size            Used            Priority
(empty - no swap configured)

5. Redimensionamiento de instancia sin migración de swap

Problema: Redimensionar un droplet no migra automáticamente el espacio de swap.

Solución: Recrear el swap después del redimensionamiento:

# After resize to larger instance
swapoff /swapfile 2>/dev/null || true
fallocate -l 4G /swapfile
chmod 600 /swapfile
mkswap /swapfile
swapon /swapfile

6. Corrupción de caché de npm

Problema: La caché de npm corrupta puede causar uso excesivo de memoria durante la instalación.

Solución: Limpiar la caché antes de reintentar:

# Clear npm cache
npm cache clean --force

# Clear sharp-specific cache
rm -rf ~/.npm/_cacache
rm -rf /tmp/sharp-*

# Retry installation
curl -fsSL https://openclaw.ai/install.sh | bash

7. Límites de memoria cgroup en contenedores

Problema: Los entornos de contenedores (LXC, Docker) pueden imponer límites de memoria cgroup que omiten el swap del sistema.

Solución: Verificar los límites de cgroup:

$ cat /sys/fs/cgroup/memory.max
18446744073709551615

# If limited (e.g., 2G):
$ cat /sys/fs/cgroup/memory.max
2147483648

8. Instalación de Node.js de 32 bits

Problema: Node.js de 32 bits no puede direccionar más de 4GB, limitando la efectividad del swap.

Solución: Asegurarse de tener una instalación de 64 bits:

$ node -p "process.arch"
x64  # Must be x64, not ia32

$ file $(which node)
/usr/bin/node: ELF 64-bit LSB executable

Códigos de error y problemas lógicamente conectados

• Código de salida 137 (SIGKILL) — Proceso terminado por el OOM killer. Indica agotamiento de memoria en todo el sistema, no necesariamente un fallo de la aplicación. Ver: Node.js Issue #39362
• sharp ERR_OUT_OF_MEMORY — Variante en tiempo de ejecución cuando sharp no puede asignar memoria para operaciones de procesamiento de imágenes. Ocurre durante la manipulación real de imágenes, no solo durante la instalación.
• ENOMEM (error POSIX 12) — La llamada al sistema falló debido a memoria insuficiente. Aparece en la compilación de módulos nativos u operaciones en tiempo de ejecución.
• npm ERR! code ERR_PACKAGE_PATH_NOT_EXPORTED — Fallo de resolución de dependencias relacionado que puede ocurrir junto con problemas de memoria cuando los trabajadores de npm fallan.
• gyp ERR! build BUILDTYPE Release — Fallo de compilación nativa, a menudo un síntoma de memoria insuficiente durante la fase de construcción en lugar de dependencias faltantes.

Issues relacionados en GitHub

• OpenClaw Issue Tracker — Esta regresión específica de v2026.3.1 a v2026.3.2
• sharp#3001 — Uso de memoria durante la instalación con RAM limitada
• sharp#3520 — Reducción de la huella de memoria para operaciones de sharp
• npm#2666 — Consumo de memoria durante operaciones de instalación de npm

Configuraciones conocidas afectadas

• Droplets de DigitalOcean (planes de 1GB, 2GB)
• AWS EC2 t3.small, t3.medium (instancias de 2GB)
• Instancias de Vultr de 2GB
• Linode Nanode de 2GB
• Contenedores Docker con límite de memoria de 2GB
• Pods de Kubernetes con solicitudes/límites de memoria de 2GB

Configuraciones conocidas que funcionan

• Sistemas con ≥4GB de RAM
• Instancias con espacio de swap dedicado ≥2GB
• Docker Desktop con memoria asignada ≥4GB
• Pods de Kubernetes con límites de memoria establecidos en 4GB+