Cómo Instalar OpenClaw: Tutorial Paso a Paso (macOS, Linux, Windows)

OpenClaw tiene requisitos mínimos, pero son importantes. Si ya los tienes, estás listo en 5 minutos. Si no, tranqui, empezamos por aquí.

1. Node.js ≥ 22

OpenClaw NECESITA Node 22 o más. Chequea tu versión:

node --version
# Tiene que decir v22.x.x o más

Si no tienes Node 22, la forma TOP de instalarlo es con nvm (Node Version Manager):

# Instalar nvm (macOS / Linux)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# Reinicia la terminal y luego:
nvm install 22
nvm use 22
nvm alias default 22

# Chequea que todo good:
node --version  # → v22.x.x

2. Gestor de paquetes: npm, pnpm o bun

npm ya viene con Node.js. Si eres team pnpm o team bun, también funcionan perfecto, tú eliges.

3. Cuenta en Anthropic u OpenAI

OpenClaw es literalmente el puente — necesita un cerebro. El proyecto recomienda Claude Pro o Claude Max (Anthropic) porque es más resistente a prompt-injection y tiene contexto larguísimo. También funciona con OpenAI (GPT-4) o con modelos locales usando Ollama.

⚠️ Ojo: OpenClaw es gratis (MIT License). El modelo de IA NO es gratis (salvo que uses Ollama con modelos locales, donde el coste es cero).

4. Sistema operativo

• macOS: soporte nativo completo, incluyendo app de barra de menú
• Linux: soporte completo, el GOAT para servidores 24/7
• Windows: vía WSL2 obligatorio (Windows nativo literalmente NO funciona, no insistas)

Estos 3 comandos funcionan en macOS, Linux y WSL2. Literal copia y pega y ya:

Paso 1: Instalar OpenClaw globalmente

# Con npm (viene con Node):
npm install -g openclaw@latest

# Alternativa con pnpm:
pnpm add -g openclaw@latest

# Alternativa con bun:
bun add -g openclaw@latest

# Chequea que se instaló:
openclaw --version

Paso 2: Ejecutar el wizard de onboarding

openclaw onboard --install-daemon

El flag --install-daemon instala OpenClaw como servicio del sistema para que arranque solo. El wizard interactivo te va a pedir:

• Credenciales del modelo (API key de Anthropic u OpenAI)
• Configuración del workspace
• Canal inicial (WhatsApp, Telegram, etc.)
• Políticas de acceso (allowlist, dmPolicy)

Paso 3: Verificar con openclaw doctor

openclaw doctor

Este comando te chequea TODO:

• ✅ Versión de Node correcta
• ✅ Gateway corriendo y accesible
• ✅ Credenciales del modelo válidas
• ✅ Configuración de canales
• ✅ Políticas de DM

Si ves todo en verde, tu asistente ya está listo. Si hay errores, tranqui, openclaw doctor te dice EXACTAMENTE qué corregir.

macOS tiene el soporte más completo de OpenClaw, es el que tiene el soporte más completo. Además de la instalación base (los 3 comandos de arriba), obtienes:

App de barra de menú (OpenClaw.app):

• Acceso rápido al estado del Gateway desde la barra de menú
• Canvas visual para interacciones gráficas
• Voice Wake: activas el asistente con solo decir su nombre
• Talk Mode: conversación continua por voz, como hablar por teléfono con tu IA

Integración con iMessage:

En macOS puedes conectar OpenClaw directo a iMessage de dos formas:

• BlueBubbles (recomendado): más estable, funciona como servidor de iMessage. Es la que tienes que usar.
• Integración legacy directa: solo macOS, puede ser inestable (puede ser inestable)

Verificar que todo funciona en macOS:

# Verificación completa
openclaw doctor

# Comprobar el daemon
launchctl list | grep openclaw

# Arrancar manualmente si se puso tricky
openclaw gateway --port 18789 --verbose

Tip para devs en Mac: Si usas Homebrew y tienes mil versiones de Node instaladas, asegúrate de que nvm use 22 está activo ANTES de instalar. Sino vas a instalar en la versión wrong y tendrás problemas.

Linux es el setup recomendado para producción punto. OpenClaw corriendo en un server Linux = tu asistente disponible 24/7, sin depender de que tu laptop esté encendida. Es la opción más fiable.

Instalación base: Los mismos 3 comandos de la sección anterior. Funcionan en Ubuntu, Debian, Fedora, Arch y derivados. Todas las distribuciones.

El daemon con systemd:

El flag --install-daemon te crea un servicio de systemd automáticamente. Para gestionarlo:

# Ver estado del servicio
systemctl --user status openclaw

# Arrancar el servicio
systemctl --user start openclaw

# Detener
systemctl --user stop openclaw

# Reiniciar
systemctl --user restart openclaw

# Ver logs del servicio
journalctl --user -u openclaw -f

Setup en VPS (DigitalOcean, Hetzner, Linode):

1. Provisionar una VM con Ubuntu 22.04+ (mínimo 1 vCPU, 1 GB RAM — eso ya basta)
2. Instalar Node 22 con nvm
3. Seguir los 3 comandos de instalación
4. Habilitar el daemon para que sobreviva reinicios: loginctl enable-linger $USER

Setup con Raspberry Pi:

Funciona en Pi 4 o superior con 4 GB+ de RAM. Si ADEMÁS quieres correr modelos locales con Ollama, necesitas mínimo 8 GB. Tu Raspberry Pi puede tener su propio asistente de IA.

Windows nativo NO está soportado. Period. OpenClaw necesita un entorno Unix. La solución oficial es WSL2 (Windows Subsystem for Linux 2). No es opcional, es obligatorio.

Paso 1: Instalar WSL2

# Abre PowerShell como Administrador y ejecuta:
wsl --install

# Esto instala Ubuntu por defecto. Reinicia tu PC cuando te lo pida.

Paso 2: Configurar el entorno Linux dentro de WSL2

# Abrir la terminal de Ubuntu (WSL2)
# Actualizar paquetes
sudo apt update && sudo apt upgrade -y

# Instalar nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# Reiniciar la terminal WSL2, luego:
nvm install 22
nvm use 22
nvm alias default 22

Paso 3: Instalar OpenClaw (dentro de WSL2)

npm install -g openclaw@latest
openclaw onboard --install-daemon
openclaw doctor

Consideraciones de WSL2:

• Las apps de WhatsApp y Telegram funcionan bien desde WSL2 — la red es compartida, todo good
• El rendimiento es excelente, prácticamente idéntico a Linux nativo
• Los archivos de configuración viven en ~/.openclaw/ dentro del filesystem de WSL2
• Para acceder desde Windows al filesystem WSL2: \\\\wsl$\\Ubuntu\\home\\tu-usuario\\.openclaw

Si quieres contribuir al proyecto, depurar, o usar la versión bleeding-edge (la más reciente, la que todavía está caliente del horno):

# Clonar el repositorio
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# Instalar dependencias
pnpm install

# Compilar la UI web
pnpm ui:build

# Compilar el proyecto
pnpm build

# Ejecutar el onboarding desde la build local
pnpm openclaw onboard --install-daemon

# Modo desarrollo con auto-reload ( Developers )
pnpm gateway:watch

Estructura del proyecto:

• packages/core/ — lógica del Gateway (el corazón)
• packages/channels/ — integraciones con canales (WhatsApp, Telegram, etc.)
• packages/ui/ — interfaz WebChat
• packages/cli/ — herramientas de línea de comandos

Una vez que openclaw doctor te muestre todo verde, manda tu primer mensaje:

# Mensaje directo desde CLI
openclaw agent --message "¿Qué día es hoy?" --thinking high

# Enviar un mensaje por WhatsApp
openclaw message send --to +346****3456 --message "Hola, soy tu asistente OpenClaw"

# Modo interactivo (conversación continua en terminal, como un chat normal)
openclaw agent --interactive

Si el asistente te responde, Felicidades — tienes tu asistente personal de IA corriendo en TU hardware. Eso es el siguiente nivel.

Siguientes pasos:

• → Conectar OpenClaw a WhatsApp
• → Explorar todas las capacidades de OpenClaw
• → La Guía Completa de OpenClaw en Español

Estos son los errores que vas a encontrar más seguido. Todos tienen solución rápida, no te asustes.

"command not found: openclaw" después de instalar:

El directorio global de npm no está en tu PATH. Solución:

# Ver dónde están los binarios globales de npm
npm root -g

# Añade el directorio padre a tu PATH en ~/.zshrc o ~/.bashrc
# Ejemplo: export PATH="$PATH:/usr/local/lib/node_modules/.bin"

# Recarga la configuración
source ~/.zshrc  # o source ~/.bashrc

El Gateway no arranca:

El error más común es que el puerto 18789 está ocupado por otra instancia. Alguien se te adelantó.

# Verificar qué ocupa el puerto
lsof -i :18789

# Matar el proceso que lo ocupa (sin piedad)
kill -9 PID_DEL_PROCESO

# Intentar arrancar de nuevo
openclaw gateway --port 18789 --verbose

"Cannot find module" al arrancar:

# Reinstalación limpia, de cero
npm uninstall -g openclaw
npm cache clean --force
npm install -g openclaw@latest

Errores de autenticación con el modelo (Anthropic/OpenAI):

# Re-ejecutar el wizard de configuración
openclaw onboard

# Verificar las credenciales específicamente
openclaw doctor

"EACCES: permission denied" al instalar globalmente:

# Opción 1: Usar nvm (recomendado — evita este problema completamente)
nvm use 22

# Opción 2: Cambiar el directorio de npm
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH="$HOME/.npm-global/bin:$PATH"

Node version incorrecta (< 22):

# Con nvm, cambiar a la versión correcta
nvm install 22
nvm use 22
nvm alias default 22

OpenClaw se actualiza seguido. Para mantener tu instalación al día:

# Actualizar a la última versión
npm update -g openclaw

# O reinstalar la última versión (si la de arriba no funcionó)
npm install -g openclaw@latest

# Verificar la nueva versión
openclaw --version

# Comprobar que todo sigue funcionando
openclaw doctor

Tip: Después de actualizar, revisa el changelog de releases para ver si hay cambios que requieran reconfiguración. Siempre es buena idea revisarlo.