¿No puedes instalar OpenClaw? Estas 7 trampas ya las pisé yo

Actualización 2026-06-08: los nombres de modelo en los ejemplos de configuración ahora usan versiones actuales (Anthropic claude-sonnet-4-6, OpenAI gpt-5); los requisitos de Node (v22.14+, recomendado v24), los recursos y los comandos de diagnóstico se revisaron en junio de 2026. Consulta siempre docs.openclaw.ai/install.

Por enésima vez aparece un mensaje de error en rojo en la terminal. Solo querías probar OpenClaw, esa herramienta nueva, y llevas desde anoche intentando instalarla: errores de permisos de npm, contenedores Docker que se reinician una y otra vez, API keys que no funcionan… Resuelves un problema y saltan tres más. Miras los GitHub Issues y ves a montones de gente con las mismas dudas: la barrera de entrada es más alta de lo que parece.

Seguiste la documentación oficial paso a paso y aun así no arranca. La terminal llena de errores te agobia y no sabes por dónde empezar.

La buena noticia: me pasé un fin de semana entero y pisé todos los hoyos. Este artículo es la guía anti-trampas: cubre las 7 categorías de problemas más comunes al instalar OpenClaw, con pasos de diagnóstico y soluciones claras. No solo te dice qué hacer, sino por qué falla, para que la próxima vez sepas dónde mirar.

Guía de bajo coste para «criar langostas»: ArkClaw democratiza el agente de IA

OpenClaw (la langosta) está de moda pero la configuración espanta. ArkClaw de Volcano Engine de ByteDance baja el listón al suelo. Sin pelearte con servidor ni tokens: en un clic tienes un «asistente de IA» 24/7 que controla el navegador, ejecuta scripts y gestiona el calendario.

Lo importante: muy barato. 9,9 yuanes al mes; con mi código de invitación ZLKUK54M (regístrate aquí) son 8,9 yuanes. Si programas, el Coding Plan Pro puede salirte gratis.

Problemas de versión de Node.js (lo más frecuente)

Lo primero al instalar OpenClaw es comprobar la versión de Node.js. Yo empecé con el Node 16 del sistema y me salieron errores de sintaxis sin sentido.

Comprueba tu versión:

node -v

Si la versión es claramente antigua, sospecha de aquí. Según docs.openclaw.ai/install: mínimo Node.js v22.14+, recomendado Node.js v24; versiones bajas provocan incompatibilidades de sintaxis o de API en tiempo de ejecución.

Errores típicos por versión incompatible:

SyntaxError: Unexpected token '?'
TypeError: fetch is not a function

El primero suele aparecer con un runtime demasiado viejo que no soporta optional chaining; el segundo, cuando no alcanzas el mínimo oficial (v22.14+) o el node que usa el shell no coincide con el entorno. ¿Ves esto? Casi seguro es versión o PATH/nvm mal configurado.

¿Cómo solucionarlo? nvm es lo más cómodo.

Recomiendo nvm (Node Version Manager): cambias de versión sin afectar otros proyectos.

🪟 Windows:

Descarga el instalador en nvm-windows. Desinstala Node.js previo del sistema para evitar conflictos en PATH.

🐧 Linux/macOS:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc

Con nvm instalado, instala Node.js 24 (alineado con la recomendación oficial y por encima del mínimo v22.14+):

nvm install 24
nvm use 24
nvm alias default 24

El último comando fija la 24 como predeterminada en terminales nuevas.

Errores de permisos de npm (frecuente en WSL2/Linux)

Los permisos de npm me destrozaron, sobre todo en WSL2: cada npm install con EACCES.

Cómo se ve el error:

EACCES: permission denied, mkdir '/usr/local/lib/node_modules/openclaw'
EACCES: permission denied, open 'package.json'

El primero en instalación global; el segundo a menudo bajo /mnt/c en WSL2.

❌ No uses esto (de verdad):

• No sudo npm install — deja los archivos hechos un lío y empeora todo
• No chmod 777 — abres la puerta a problemas de seguridad
• No npm config set unsafe-perm true — parche temporal

✅ Tres soluciones correctas según tu caso:

Opción A: cambiar el directorio global de npm (recomendada, todos los Linux)

La idea: instalar paquetes globales en tu home, sin pelear con permisos del sistema.

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

Abre una terminal nueva e intenta de nuevo; no debería fallar por permisos.

Alibaba Cloud - Opción preferida para desarrolladores, 15 % de descuento exclusivo en Lighthouse

Obtener 15% dto. →Anuncio

Opción B: arreglar permisos del sistema de archivos en WSL2

🔧 WSL2 monta el disco de Windows (/mnt/c) con un modelo de permisos distinto; npm suele fallar ahí.

Configura /etc/wsl.conf:

sudo nano /etc/wsl.conf

Añade:

[automount]
options = "metadata,umask=22,fmask=11"

Guarda y en PowerShell de Windows:

wsl.exe --shutdown

Reabre WSL2; los permisos suelen quedar resueltos.

Opción C: trabajar en el home de WSL (lo más simple)

Lo más tranquilo: no desarrolles bajo /mnt/c. Usa ~/projects u otro directorio nativo de WSL; npm va más rápido y sin permisos raros.

mkdir ~/projects
cd ~/projects
# Instala OpenClaw aquí

Problemas con Docker

Docker puede liarse; yo también me quedé atascado. Un contenedor que no arranca puede tener muchas causas; hay que ir paso a paso.

Diagnóstico:

# Paso 1: estado de contenedores
docker compose ps

# Paso 2: logs
docker compose logs openclaw-gateway

# Paso 3: filtrar errores
docker compose logs openclaw-gateway | grep -i "error"

Estos tres pasos acotan dónde está el fallo.

Problema A: health check fallido, reinicios en bucle

El contenedor arranca unos segundos, se para y vuelve a empezar.

En los logs verás algo como:

Health check failed: container unhealthy
Container openclaw-gateway exited with code 137

Casi siempre faltan recursos. OpenClaw pide mínimo 2 vCPU / 4 GB RAM; recomendado 4 vCPU / 8 GB RAM.

¿Cómo subir recursos de Docker?

🪟 Windows/Mac: Docker Desktop → Settings → Resources, sube CPU y memoria.

🐧 Linux: suele usar todo el host; no hace falta tocar nada.

Si la máquina es justa, puedes desactivar el health check (no recomendado, pero sirve de emergencia):

# Edita docker-compose.yml
healthcheck:
  disable: true

Problema B: permisos de Docker (solo Linux)

permission denied while trying to connect to the Docker daemon socket

Tu usuario no está en el grupo docker:

sudo usermod -aG docker $USER
newgrp docker

⚠️ Seguridad: el grupo docker equivale a permisos de root; en producción o servidores compartidos valora Docker rootless.

Problema C: puerto 18789 ocupado

A veces queda un proceso OpenClaw colgado.

🐧 Linux/Mac:

lsof -i :18789

🪟 Windows:

netstat -ano | findstr 18789

Cierra el proceso con elegancia:

openclaw gateway stop

O fuerza (cambia PID por el que obtuviste):

kill -9 <PID>

Problema D: ARM64 (Mac con Apple Silicon)

En M1/M2 puede fallar la ruta de Chromium. Poco frecuente pero molesto.

Solución: Dockerfile personalizado con la ruta ARM64 de Chromium. En GitHub Issues de OpenClaw hay configs completas.

Configuración de claves API

Las API keys también me volvieron loco: en el config está la key y OpenClaw dice que no la encuentra.

Errores habituales:

No API key found for anthropic
Invalid API key format
API key validation failed

No entres en pánico; sigue esta lista.

Punto 1: ¿variables de entorno correctas?

Comprueba que estén activas:

Railway - Plataforma de despliegue moderna, sin ops complejas, en producción en minutos

Empezar ahora →Anuncio

echo $ANTHROPIC_API_KEY
echo $OPENAI_API_KEY

Si no sale nada, no están bien definidas.

Forma correcta:

# Temporal (solo esta terminal)
export ANTHROPIC_API_KEY="sk-ant-xxxxx"

# Permanente (en el perfil)
echo 'export ANTHROPIC_API_KEY="sk-ant-xxxxx"' >> ~/.bashrc
source ~/.bashrc

🔧 WSL2: las variables de WSL y Windows no se comparten; no configures solo en Windows y esperes verlas en WSL.

Punto 2: ¿formato del archivo de config?

Si usas ~/.openclaw/openclaw.json, el JSON debe ser válido. Config y estado actuales van en ~/.openclaw/; si aún usas ~/.clawdbot/, lee primero el artículo de la serie sobre el cambio de nombre y migra.

Errores que veo a menudo:

• Espacios o comillas de más
• Coma olvidada
• Coma final de más

Valida el JSON:

cat ~/.openclaw/openclaw.json | jq .

Si jq falla, el JSON está mal. Instálalo si no lo tienes:

# Ubuntu/Debian
sudo apt install jq

# macOS
brew install jq

Punto 3: ¿la key en sí?

A veces la key expiró o fue revocada.

• Anthropic Claude: https://console.anthropic.com/settings/keys
• OpenAI GPT: https://platform.openai.com/api-keys

Comprueba estado Active y límites de uso.

Consejo: diferencias entre proveedores

Para cambiar el modelo por defecto:

{
  "defaultProvider": "anthropic",
  "anthropic": {
    "apiKey": "sk-ant-xxxxx",
    "model": "claude-sonnet-4-6"
  },
  "openai": {
    "apiKey": "sk-xxxxx",
    "model": "gpt-5"
  }
}

Configuración especial en WSL2

Si usas WSL2 en Windows, muchos tutoriales Linux no encajan tal cual. Hay diferencias reales.

Tres diferencias clave:

1. Permisos de archivos — ya lo vimos con npm
2. Red separada — a veces localhost no coincide entre Windows y WSL
3. Integración con Docker Desktop — compartir Docker puede dar guerra

wsl.conf completo recomendado:

sudo nano /etc/wsl.conf

Contenido:

[automount]
enabled = true
root = /mnt/
options = "metadata,umask=22,fmask=11"

[interop]
enabled = true
appendWindowsPath = true

[network]
generateResolvConf = true

Reinicia WSL2:

# En PowerShell de Windows
wsl.exe --shutdown

Integración WSL2 en Docker Desktop

1. Abre Docker Desktop
2. Settings → Resources → WSL Integration
3. Marca tu distro (p. ej. Ubuntu)
4. Apply & Restart

Rendimiento: evita cruzar sistemas de archivos

Mi peor trampa: código en D: de Windows (/mnt/d en WSL) y npm install eterno.

Operar entre WSL y archivos de Windows baja el rendimiento un 50-90 %; no es exageración.

Lo correcto:

# Trabaja en el home de WSL
cd ~
mkdir projects
cd projects
git clone https://github.com/openclaw/openclaw.git

Todo en el sistema de archivos nativo (/home/usuario).

Límite de recursos (opcional)

Si tienes poca RAM, crea .wslconfig en tu usuario de Windows:

# C:\Users\tu_usuario\.wslconfig
[wsl2]
memory=4GB
processors=2
swap=2GB

OpenClaw ya es exigente; limitar demasiado puede impedir que arranque.

Timeout e dependencias al instalar skills

También me pasó con skills: la primera instalación tarda y parece colgada.

Diagnóstico:

openclaw skill check <skill-name>

Muestra estado y errores.

Logs del Gateway:

docker compose logs openclaw-gateway | grep -i "skill"

Dependencias habituales:

Problema A: binarios faltantes

Vultr - Servidor cloud NVMe de alto rendimiento, 32 ubicaciones globales, despliegue Docker con un clic

Ver precios →Anuncio

Algunos skills piden Go u otras dependencias del sistema.

Instala lo que indiquen los logs:

# Por ejemplo falta Go
sudo apt install golang-go

# O dependencias Python
sudo apt install python3-dev

Problema B: timeout de red

Lo más común en la primera instalación: muchas descargas y red lenta.

Síntoma: barra quieta, logs con timeout o connection refused.

Solución simple: reintentar.

openclaw skill install <skill-name>

En China puedes acelerar npm:

npm config set registry https://registry.npmmirror.com

También hay mirrors de Docker; hay muchos tutoriales.

Problema C: OS no soportado

Algunos skills solo se probaron en Ubuntu 22.04; otra distro puede fallar.

Busca en GitHub Issues workarounds.

Consejo:

Skills con dependencias Go pueden tardar 5-10 minutos la primera vez. Si el log sigue moviéndose, no pulses Ctrl+C.

Flujo sistemático de diagnóstico

Resumen de un proceso ordenado cuando no sabes por dónde empezar.

Comandos de diagnóstico de OpenClaw:

# Estado del servicio
openclaw status

# Health check
openclaw health

# Diagnóstico completo (recomendado)
openclaw doctor

openclaw doctor revisa versión de Node, Docker, claves API, puertos, etc., y devuelve un informe.

Leer logs:

• Nivel ERROR — grep -i "error"
• Primer error — los siguientes suelen ser efecto dominó
• Stack trace — localiza la línea concreta

¿Cuándo abrir un GitHub Issue?

Si seguiste todo y sigue fallando, puede ser un bug real.

Prepara:

• SO y versión (Windows 11 + WSL2 Ubuntu 22.04 / macOS 14 / Ubuntu 22.04)
• Node.js (node -v)
• OpenClaw (openclaw --version)
• Logs completos en bloques de código
• Pasos para reproducir

Cuanto más detalle, más fácil ayudarte.

Conclusión

Repaso rápido de las siete categorías:

1. Node.js — nvm con Node 24 (o mínimo v22.14+), alineado con la doc oficial
2. Permisos npm — directorio global en home o trabajar en directorio nativo WSL
3. Docker — logs primero; suele ser recursos o puerto ocupado
4. Claves API — variables de entorno, JSON válido, key activa
5. WSL2 — wsl.conf y no cruzar sistemas de archivos
6. Skills — reintentar si es red; instalar dependencias que falten
7. Diagnóstico sistemático — openclaw doctor y revisar en orden

Instalar OpenClaw requiere paciencia, pero estos hoyos no se repiten. Lo clave es un método: no entrar en pánico ante el error, ver qué capa falla y actuar.

Guarda esta lista para la próxima vez. Si te ayudó, compártela con quien también esté peleándose con OpenClaw.

¿Algo que no cubrimos? Comenta y seguiré actualizando la guía.