Aplica a OpenClaw v2026.2 | Este artículo asume que tienes un entorno Node.js >= 22 y una API Key de IA (se recomienda Anthropic Claude).

TL;DR: Completa la instalación de OpenClaw en 5 minutos. Soporta cuatro métodos: npm/pnpm/bun/Docker, se recomienda npm install -g openclaw@latest && openclaw onboard. El archivo de configuración está en ~/.openclaw/openclaw.json, se inicia con openclaw gateway. Cubre en detalle el despliegue con Docker, estructura del archivo de configuración y resolución de problemas comunes.

Requisitos previos

Entorno necesario

Entorno recomendado

API Key de IA

OpenClaw necesita conectarse a un modelo de IA para funcionar. Se recomienda:

💡 Recomendado: Anthropic Claude Opus 4.6 ofrece la mejor capacidad de procesamiento de contexto largo y protección contra inyección de prompts.

Verificación del entorno

# Verificar versión de Node.js
node --version
# Salida ejemplo: v22.12.0

# Verificar versión de npm
npm --version
# Salida ejemplo: 10.9.0

# Verificar información del sistema
uname -a  # Linux/macOS
# o
systeminfo | findstr /B /C:"OS Name" /C:"OS Version"  # Windows

Comparación de métodos de instalación

flowchart TB
    A[Elegir método de instalación] --> B{Caso de uso?}
    B -->|Prueba rápida| C[Instalación global npm]
    B -->|Uso diario| D[Instalación pnpm/bun]
    B -->|Despliegue en producción| E[Despliegue Docker]
    B -->|Contribuir al desarrollo| F[Compilación desde fuente]
    
    C --> G[5 minutos para completar]
    D --> H[Gestión de dependencias más rápida]
    E --> I[Aislamiento del entorno reproducible]
    F --> J[Personalizable participar en desarrollo]

Tabla comparativa de métodos

Método uno: Instalación global npm (recomendado para principiantes)

Pasos de instalación

# 1. Instalar la última versión estable
npm install -g openclaw@latest

# 2. Verificar la instalación
openclaw --version
# Salida ejemplo: 2026.2.26

# 3. Ver la ayuda
openclaw --help

Estructura de directorios post-instalación

/usr/local/lib/node_modules/openclaw/  # Directorio de instalación global
├── bin/
│   └── openclaw                        # Archivo ejecutable
├── lib/
│   └── ...                             # Archivos de biblioteca central
└── package.json

~/.openclaw/                            # Directorio de datos de usuario (creado en la primera ejecución)
├── openclaw.json                       # Archivo de configuración principal
├── credentials/                       # Almacenamiento de credenciales de canales
├── workspace/                          # Espacio de trabajo del Agent
│   ├── AGENTS.md                      # Guía de comportamiento del Agent
│   ├── SOUL.md                        # Configuración de personalidad del Agent
│   └── skills/                        # Skills personalizados
└── logs/                              # Directorio de logs

Ejecutar el asistente de configuración

# Iniciar el asistente de configuración interactivo
openclaw onboard --install-daemon

El asistente te guiará para completar:

sequenceDiagram
    participant U as Usuario
    participant W as Asistente
    participant S as Sistema
    
    U->>W: Iniciar onboard
    W->>U: Seleccionar proveedor de modelo
    U->>W: Seleccionar Anthropic
    W->>U: Introducir API Key
    U->>W: Pegar Key
    W->>U: Seleccionar puerto del Gateway
    U->>W: 18789 (por defecto)
    W->>U: ¿Instalar el daemon?
    U->>W: Sí
    W->>S: Crear servicio systemd/launchd
    S-->>W: Instalación exitosa
    W-->>U: ¡Configuración completada!

Método dos: Instalación pnpm (recomendado para uso diario)

Instalar pnpm

# Instalar pnpm con npm
npm install -g pnpm

# O usar el script independiente
curl -fsSL https://get.pnpm.io/install.sh | sh -

Instalar OpenClaw

# Instalar con pnpm
pnpm add -g openclaw@latest

# Verificar
openclaw --version

Ventajas de pnpm

Método tres: Instalación con bun (para máxima velocidad)

Instalar bun

# macOS/Linux
curl -fsSL https://bun.sh/install | bash

# O con npm
npm install -g bun

Instalar OpenClaw

# Instalar con bun
bun add -g openclaw@latest

# Verificar
openclaw --version

Ventajas de bun

Método cuatro: Despliegue con Docker (recomendado para producción)

Obtener la imagen

# Descargar la imagen más reciente
docker pull openclaw/openclaw:latest

# O especificar versión
docker pull openclaw/openclaw:2026.2

Ejecución básica

# Ejecución mínima
docker run -d \
  --name openclaw \
  -p 18789:18789 \
  -v ~/.openclaw:/root/.openclaw \
  -e ANTHROPIC_API_KEY=your_key_here \
  openclaw/openclaw:latest

# Ver logs
docker logs -f openclaw

Configuración Docker Compose

Crear docker-compose.yml:

version: '3.8'

services:
  openclaw:
    image: openclaw/openclaw:latest
    container_name: openclaw
    restart: unless-stopped
    ports:
      - "18789:18789"
    volumes:
      - ./openclaw-data:/root/.openclaw
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      # O usar archivo de configuración
      # - OPENCLAW_CONFIG=/root/.openclaw/openclaw.json
    healthcheck:
      test: ["CMD", "openclaw", "health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

Iniciar el servicio:

# Crear archivo .env
echo "ANTHROPIC_API_KEY=your_key_here" > .env

# Iniciar
docker-compose up -d

# Ver estado
docker-compose ps

# Ver logs
docker-compose logs -f

Configuración de red Docker

# Configuración extendida de docker-compose.yml
services:
  openclaw:
    # ... otras configuraciones
    networks:
      - openclaw-net

  # Opcional: proxy inverso
  caddy:
    image: caddy:latest
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
    networks:
      - openclaw-net

networks:
  openclaw-net:
    driver: bridge

Método cinco: Compilación desde fuente (desarrolladores)

Clonar el repositorio

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

# Instalar dependencias (se recomienda pnpm)
pnpm install

# Compilar
pnpm build

# Ejecutar
pnpm openclaw onboard

Modo desarrollo

# Modo desarrollo (recarga automática)
pnpm gateway:watch

# Ejecutar pruebas
pnpm test

# Revisión de código
pnpm lint

Explicación detallada del archivo de configuración

Prioridad de configuración

Parámetros CLI > Variables de entorno > Archivo de configuración > Valores por defecto

Estructura de directorios

~/.openclaw/
├── openclaw.json           # Archivo de configuración principal
├── openclaw.json.backup    # Copia de seguridad automática
├── credentials/            # Credenciales sensibles (cifrado automático)
│   ├── telegram.json
│   ├── whatsapp.json
│   └── discord.json
├── workspace/              # Espacio de trabajo del Agent
│   ├── AGENTS.md          # Guía de comportamiento global
│   ├── SOUL.md            # Personalidad del Agent
│   ├── TOOLS.md           # Instrucciones de herramientas personalizadas
│   ├── USER.md            # Información del usuario
│   └── skills/            # Directorio de skills
│       ├── gmail/
│       │   └── SKILL.md
│       └── calendar/
│           └── SKILL.md
├── sessions/              # Datos de sesiones
├── logs/                  # Archivos de logs
│   ├── gateway.log
│   └── agent.log
└── cache/                 # Datos de caché

Configuración mínima

~/.openclaw/openclaw.json:

{
  "agent": {
    "model": "anthropic/claude-opus-4-6"
  }
}

Ejemplo de configuración completa

{
  "agent": {
    "model": "anthropic/claude-opus-4-6",
    "thinkingLevel": "high",
    "verboseLevel": "normal"
  },
  "gateway": {
    "port": 18789,
    "bind": "loopback",
    "host": "127.0.0.1"
  },
  "channels": {
    "telegram": {
      "botToken": "YOUR_BOT_TOKEN",
      "dmPolicy": "pairing",
      "allowFrom": []
    },
    "whatsapp": {
      "allowFrom": ["+8613800138000"],
      "groups": {
        "*": { "requireMention": true }
      }
    },
    "discord": {
      "token": "YOUR_DISCORD_TOKEN",
      "guilds": {}
    }
  },
  "agents": {
    "defaults": {
      "workspace": "~/.openclaw/workspace",
      "sandbox": {
        "mode": "off"
      }
    }
  },
  "models": {
    "fallback": [
      {
        "model": "anthropic/claude-sonnet-4",
        "condition": "rate_limit"
      }
    ]
  },
  "webhooks": [],
  "cron": []
}

Descripción de opciones de configuración

Variables de entorno

OpenClaw permite sobrescribir la configuración mediante variables de entorno:

# API Keys
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."

# Configuración de canales
export TELEGRAM_BOT_TOKEN="123456:ABC..."
export DISCORD_BOT_TOKEN="..."

# Configuración del Gateway
export OPENCLAW_PORT=18789
export OPENCLAW_BIND="loopback"

Inicio y verificación

Iniciar el Gateway

# Ejecución en primer plano (modo depuración)
openclaw gateway --verbose

# Ejecución en segundo plano (daemon)
openclaw gateway --daemon

# Especificar puerto
openclaw gateway --port 18790

Verificar el estado de ejecución

# Verificar estado de salud
openclaw doctor

# Salida ejemplo:
# ✓ Node.js version: v22.12.0
# ✓ OpenClaw version: 2026.2.26
# ✓ Gateway running on port 18789
# ✓ API key configured
# ✓ Workspace directory exists

Acceder a la consola web

Después de iniciar el Gateway, abre el navegador y accede a:

http://127.0.0.1:18789

Verás la Web Control UI:

Probar la conversación

# Prueba desde línea de comandos
openclaw agent --message "Hola, preséntate por favor"

# Salida ejemplo:
# ¡Hola! Soy tu asistente OpenClaw. Puedo ayudarte con...

Resolución de problemas comunes

Problema 1: Puerto ocupado

Síntoma:

Error: EADDRINUSE: address already in use 127.0.0.1:18789

Solución:

# Encontrar el proceso que ocupa el puerto
lsof -i :18789
# o
netstat -tlnp | grep 18789

# Terminar el proceso
kill -9 <PID>

# O usar otro puerto
openclaw gateway --port 18790

Problema 2: API Key inválida

Síntoma:

Error: Invalid API key

Solución:

# Verificar configuración
openclaw config get agent.model

# Verificar variable de entorno
echo $ANTHROPIC_API_KEY

# Reconfigurar
openclaw onboard

Problema 3: Versión de Node demasiado antigua

Síntoma:

Error: OpenClaw requires Node.js >= 22.0.0

Solución:

# Cambiar versión con nvm
nvm install 22
nvm use 22
nvm alias default 22

# Verificar
node --version

Problema 4: Problema de permisos

Síntoma:

Error: EACCES: permission denied

Solución:

# Corregir permisos de npm
sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) ~/.openclaw

# O gestionar Node.js con nvm (recomendado)

Problema 5: Problema de red Docker

Síntoma:

Error: Cannot connect to Gateway from container

Solución:

# Verificar red
docker network ls
docker network inspect bridge

# Usar red del host
docker run --network host ...

# O mapear puertos correctamente
docker run -p 127.0.0.1:18789:18789 ...

Problema 6: Credenciales perdidas

Síntoma:

Warning: Telegram credentials not found

Solución:

# Volver a iniciar sesión en el canal
openclaw channels login telegram

# Verificar archivos de credenciales
ls ~/.openclaw/credentials/

# Hacer copia de seguridad de credenciales
cp -r ~/.openclaw/credentials/ ~/.openclaw/credentials.backup/

Problema 7: Memoria insuficiente

Síntoma:

Error: JavaScript heap out of memory

Solución:

# Aumentar el límite de memoria de Node.js
export NODE_OPTIONS="--max-old-space-size=8192"
openclaw gateway

# O en Docker
docker run -e NODE_OPTIONS="--max-old-space-size=8192" ...

Actualización y mantenimiento

Actualizar OpenClaw

# Actualización con npm
npm update -g openclaw@latest

# Actualización con pnpm
pnpm update -g openclaw@latest

# Actualización con Docker
docker pull openclaw/openclaw:latest
docker-compose up -d

# Verificar versión
openclaw --version

Cambiar canal de lanzamiento

# Versión estable (recomendada)
openclaw update --channel stable

# Versión beta
openclaw update --channel beta

# Versión de desarrollo (últimas funciones, puede ser inestable)
openclaw update --channel dev

Copia de seguridad y restauración

# Copia de seguridad de configuración
tar -czvf openclaw-backup-$(date +%Y%m%d).tar.gz ~/.openclaw/

# Restaurar configuración
tar -xzvf openclaw-backup-20260226.tar.gz -C ~/

# Solo hacer copia de seguridad de archivos clave
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup
cp -r ~/.openclaw/credentials/ ~/.openclaw/credentials.backup/

Próximos pasos

¡Felicitaciones! Has configurado exitosamente el entorno de OpenClaw. A continuación:

1. Configurar el primer canal → Siguiente artículo: Configuración de canales
2. Instalar el primer Skill → Buscar e instalar desde la Web UI
3. Personalizar la personalidad del Agent → Editar ~/.openclaw/workspace/SOUL.md

Resumen de este artículo:

• Dominaste 5 métodos de instalación y sus escenarios de uso
• Entendiste la estructura y prioridad del archivo de configuración
• Aprendiste la verificación de inicio y resolución de problemas comunes
• Conociste las operaciones básicas de actualización y mantenimiento

Historial de actualizaciones:

• 2026-02-26: Versión inicial publicada, basada en OpenClaw v2026.2

Navegación de la serie:

• ← Anterior: Introducción a OpenClaw
• → Siguiente: Configuración de canales: Comenzando con Telegram