Ejecutando OpenClaw en Docker: una guia de despliegue paso a paso

¿Por que Docker?

Ejecutar OpenClaw en Docker proporciona tres ventajas clave sobre una instalacion en metal desnudo:

1. 1.Aislamiento de seguridad: El agente se ejecuta dentro de un contenedor con acceso limitado a tu sistema anfitrion. Si un skill malicioso o una inyeccion de prompt intenta acceder a tus archivos, el limite del contenedor reduce el radio de explosion.
2. 2.Reproducibilidad: La misma imagen de Docker se ejecuta de forma identica en cualquier maquina — tu portatil, un VPS o una Raspberry Pi.
3. 3.Limpieza facil: ¿Quieres empezar de cero? Elimina el contenedor y levanta uno nuevo. Sin archivos residuales, sin instalaciones rotas de Node.js.

Prerequisitos

• •Docker Desktop (macOS/Windows) o Docker Engine (Linux)
• •Docker Compose v2 (incluido con Docker Desktop)
• •Al menos 2 GB de RAM disponibles para el contenedor
• •Una clave API de IA (Anthropic, OpenAI u otro proveedor compatible)

Inicio rapido

Opcion A: Docker Compose oficial (recomendado)

Clona el repositorio de OpenClaw y usa la configuracion de Docker incorporada:

git clone https://github.com/openclaw/openclaw.git
cd openclaw

Ejecuta el script de configuracion, que crea los directorios y configuracion necesarios:

bash docker-setup.sh

• •~/.openclaw/ — configuracion, SOUL.md, claves API
• •~/openclaw/workspace/ — archivos accesibles para el agente

Ejecuta el asistente de incorporacion dentro del contenedor:

docker compose run --rm openclaw-cli onboard

Sigue las indicaciones para configurar tu clave API y conectar una plataforma de chat. Luego inicia el gateway:

docker compose up -d openclaw-gateway

Tu agente ahora esta ejecutandose en segundo plano.

Opcion B: Imagen preconstruida

Si no quieres clonar el repositorio, usa la imagen oficial preconstruida:

docker run -d \
  --name openclaw \
  --restart unless-stopped \
  -v ~/.openclaw:/root/.openclaw \
  -v ~/openclaw/workspace:/root/workspace \
  -p 3000:3000 \
  ghcr.io/openclaw/openclaw:latest

Referencia de Docker Compose

Aqui tienes un docker-compose.yml anotado para uso en produccion:

version: "3.8"
services:
  openclaw-gateway:
    image: ghcr.io/openclaw/openclaw:latest
    container_name: openclaw
    restart: unless-stopped
    ports:
      - "3000:3000"        # Web UI
    volumes:
      - ~/.openclaw:/root/.openclaw          # Config and data
      - ~/openclaw/workspace:/root/workspace  # Agent workspace
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - TZ=Asia/Shanghai     # Set your timezone
    mem_limit: 2g            # Prevent runaway memory usage
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

Crea un archivo .env en el mismo directorio con tus claves API:

ANTHROPIC_API_KEY=sk-ant-xxxxx
OPENAI_API_KEY=sk-xxxxx

Variables de entorno

*Se requiere al menos una clave de proveedor de IA.

Gestionando tu contenedor

# Ver logs
docker logs -f openclaw

# Detener el agente
docker compose stop

# Iniciar el agente
docker compose up -d

# Reiniciar despues de cambios de configuracion
docker compose restart

# Actualizar a la ultima version
docker compose pull
docker compose up -d

# Entrar al shell del contenedor
docker exec -it openclaw bash

# Ejecutar comandos CLI dentro del contenedor
docker exec openclaw openclaw skill list
docker exec openclaw openclaw status

Endurecimiento de seguridad

Limitar el acceso al sistema de archivos

Monta solo los directorios que tu agente realmente necesita. Evita montar todo tu directorio personal:

volumes:
  - ~/.openclaw:/root/.openclaw:rw     # Config (read-write)
  - ~/documents:/root/docs:ro           # Documents (read-only)

Aislamiento de red

Si tu agente no necesita acceder a servicios de la red local, restringe su red:

networks:
  openclaw-net:
    driver: bridge
    internal: false    # Set to true to block all external access

Sistema de archivos raiz de solo lectura

Para maxima seguridad, haz el sistema de archivos raiz de solo lectura y solo permite escrituras en rutas especificas:

read_only: true
tmpfs:
  - /tmp
  - /run

Actualizacion

OpenClaw lanza versiones frecuentemente. Para actualizar tu despliegue de Docker:

docker compose pull           # Pull latest image
docker compose up -d          # Recreate container with new image
docker image prune -f         # Clean up old images

Tu configuracion y datos persisten en los volumenes montados, por lo que las actualizaciones no son destructivas.

Solucion de problemas

El contenedor se cae inmediatamente: Verifica los logs con docker logs openclaw. Causas comunes: claves API faltantes, memoria insuficiente o conflictos de puertos.

El codigo QR de WhatsApp no aparece: Ejecuta la incorporacion en modo interactivo: docker compose run --rm openclaw-cli onboard. El codigo QR necesita una terminal que soporte renderizado.

Errores de permisos en volumenes montados: Asegurate de que los directorios del host existan y pertenezcan a tu usuario: mkdir -p ~/.openclaw ~/openclaw/workspace.

Alto uso de memoria: Establece mem_limit: 2g en docker-compose.yml para evitar que el contenedor consuma RAM excesiva.

Para mas detalles, consulta la documentacion oficial de Docker y el docker-compose.yml en el repositorio.