OpenClaw Setup: los errores de las primeras 72 horas

Llevas dos días con OpenClaw instalado. Has probado algunos comandos, el agente responde, parece que funciona. Y entonces haces lo que hace prácticamente todo el mundo: decides construir un dashboard de control para ver el estado del agente en tiempo real.

Es el error más caro que puedes cometer en estas primeras horas.

TL;DR: OpenClaw es un runtime de agente personal open-source que conecta tu agente con Telegram, Slack o WhatsApp y le da acceso a tu sistema de archivos y terminal. La mayoría de usuarios nuevos fracasa por el mismo motivo: construyen antes de dar contexto. Esta guía cubre el setup correcto, cómo rellenar los archivos de workspace (AGENTS.md, SOUL.md, TOOLS.md) y cómo controlar el consumo de tokens desde el primer día.

La trampa del dashboard de control

Construir una interfaz de monitorización antes de tener un workflow real consume tokens en exploración sin valor, introduce complejidad prematura y te distrae del único objetivo que importa en estas primeras horas: que el agente haga algo útil de verdad.

La trampa del dashboard es seductora porque parece progreso. Estás construyendo infraestructura. Pero un agente que monitoriza a un agente que no hace nada útil es solo ruido caro. Antes de pensar en observabilidad, necesitas algo que observar.

El segundo error en frecuencia es empezar a pedir tareas al agente sin haber configurado su contexto. Sin AGENTS.md con instrucciones claras, sin USER.md con tus preferencias, el agente opera en modo genérico. Puede responder, pero lo hace como si nunca te hubiera visto antes, en cada sesión, de forma indefinida.

¿Qué es OpenClaw y cómo funciona su memoria?

OpenClaw es un runtime de agente personal open-source que se ejecuta en local y conecta tu agente con las aplicaciones de mensajería que ya usas. A diferencia de un chatbot, tiene acceso real al sistema: puede ejecutar comandos de terminal, automatizar navegadores, gestionar archivos y lanzar tareas programadas mediante un sistema de Heartbeat que actúa como un planificador periódico.

Lo que diferencia a OpenClaw de una llamada directa a la API de Claude es su sistema de workspace. El agente no arranca de cero en cada sesión: lee un conjunto de archivos de contexto que definen quién eres, qué quieres y cómo debe comportarse. Estos archivos viven en ~/.openclaw/workspace/ y se inyectan en el contexto del sistema en cada turno de conversación.

Los archivos principales son:

AGENTS.md: el contrato de operaciones. Prioridades, límites, flujo de trabajo y nivel de calidad esperado. Es el archivo más importante del workspace.
SOUL.md: la identidad del agente. Voz, temperamento, valores y restricciones. Define personalidad, no tareas.
TOOLS.md: notas sobre herramientas locales y convenciones del proyecto. No controla qué herramientas están disponibles; es solo orientación contextual.
USER.md: preferencias del usuario. Tono de comunicación, formato de salida y restricciones conocidas.
MEMORY.md: memoria a largo plazo curada automáticamente. El agente escribe aquí lo que aprende entre sesiones.

Sin estos archivos correctamente configurados, cada sesión es como el primer día. El agente no recuerda tus proyectos, tus preferencias ni las decisiones tomadas la semana anterior.

El setup correcto: contexto primero, construcción después

El orden que funciona es este: rellena los archivos de workspace antes de pedir cualquier tarea. Es el equivalente a hacer un onboarding real con un empleado nuevo, en lugar de soltarle en su primer día sin explicarle nada.

Paso 1: instalación

OpenClaw requiere Node.js 22 o superior. La instalación global con npm es la opción más directa:

# Instalación global
npm install -g openclaw@latest

# Verificar versión instalada
openclaw --version

# Lanzar el wizard de onboarding (instala el daemon del gateway)
openclaw onboard --install-daemon

El wizard guía la configuración del proveedor de IA, los canales de mensajería y el workspace inicial. No saltes pasos: algunas preguntas del wizard tienen impacto directo en el comportamiento del agente a largo plazo.

Paso 2: verificar que el gateway está activo

# Comprobar estado del gateway
curl http://localhost:3000/health

# Diagnóstico de configuración y permisos
openclaw doctor

Un 200 OK en el health check confirma que el gateway está activo. Si openclaw doctor reporta problemas, resuélvelos antes de continuar. Un gateway con errores de configuración silenciosos es una fuente habitual de comportamiento inesperado en producción.

Paso 3: conectar Telegram

Telegram es el canal con mejor soporte y menor latencia para OpenClaw. Crea un bot en BotFather, obtén el token y configúralo:

# Añadir canal Telegram (el wizard solicita el token del bot)
openclaw channel add telegram

Rellenar los archivos de workspace

Este es el paso que casi nadie hace correctamente. La tentación es dejar los archivos con el contenido por defecto y "ya los editaré después". Ese después no llega, y el agente opera durante semanas con instrucciones genéricas.

AGENTS.md: el contrato de operaciones

# Contrato de operaciones

## Prioridades
1. Completar tareas con el mínimo de tokens necesario
2. Pedir confirmación antes de ejecutar acciones irreversibles
3. Reportar errores con contexto suficiente para depurar

## Workflow
- Para tareas de más de 3 pasos: desglosa el plan antes de ejecutar
- Para archivos: trabaja en ~/.openclaw/workspace/ salvo indicación contraria
- Para código: Python 3.12+ con type hints, sin dependencias innecesarias

## Límites
- No envíes mensajes externos sin confirmación explícita
- No ejecutes comandos con sudo sin aprobación previa
- No accedas a directorios fuera del workspace sin autorización

## Calidad
- Respuestas concisas: si cabe en 2 frases, no uses 10
- Preferencia por listas sobre párrafos cuando hay más de 2 puntos

SOUL.md: la identidad del agente

# Identidad del agente

## Voz y temperamento
- Directo y técnico, sin rodeos innecesarios
- Honesto sobre limitaciones: si no sé algo, lo digo
- Proactivo cuando hay algo relevante que reportar

## Valores
- Privacidad: no almacenar datos sensibles en MEMORY.md
- Reversibilidad: preferir acciones que se puedan deshacer
- Transparencia: explicar qué hace y por qué cuando no es obvio

TOOLS.md: convenciones de herramientas

# Herramientas y convenciones

## Sistema
- OS: Ubuntu 22.04 LTS en VPS
- Shell: bash
- Gestor de paquetes Python: pip con venv

## Proyectos activos
- Blog: /var/www/blog/ (Astro + Vercel CI/CD)
- Scripts: ~/scripts/

## Convenciones
- Commits en inglés siguiendo Conventional Commits
- Variables de entorno en .env (nunca hardcodeadas)

Para AGENTS.md, pon reglas estables a largo plazo, no listas de tareas. Las tareas puntuales van en los mensajes al agente, no en el archivo de instrucciones. Si mezclas ambas cosas, el archivo crece y se vuelve incoherente con el tiempo.

El primer workflow real: no experimentos

Una vez configurado el contexto, el primer workflow debe ser concreto, repetible y con valor tangible desde el primer día. No un experimento para "ver qué hace el agente".

Un buen punto de partida es el informe matutino por Telegram: cada día a las 08:00, el agente envía un resumen de tareas pendientes y noticias relevantes. Es simple, medible y útil desde el primer uso. Para configurarlo, añade esto a tu HEARTBEAT.md:

# Heartbeat: informe matutino

## Programación
- Hora: 08:00 (Europe/Madrid)
- Frecuencia: lunes a viernes

## Tarea
1. Leer archivos en ~/tasks/pending/
2. Buscar noticias de IA y automatización (últimas 24 horas)
3. Generar resumen de máximo 300 palabras
4. Enviar por Telegram al canal principal

## Modelo
- Usar claude-haiku-4-5-20251001 (coste mínimo, suficiente para resúmenes)

Este ejemplo ilustra un principio que reduce el coste mensual de forma significativa: usa el modelo más barato que resuelva la tarea. Haiku para resúmenes y clasificaciones, Sonnet para razonamiento medio, Opus solo cuando la complejidad lo justifica. La diferencia entre Haiku y Opus puede ser 25x para el mismo número de tokens.

Para flujos donde el agente necesita coordinar subtareas con revisión entre ellas, el patrón de boss agent con ciclo de crítica es una referencia útil de arquitectura multi-agente.

En Producción

Lo que funciona en local con una sesión de prueba se comporta diferente cuando el agente lleva días activo con historial acumulado. Estos son los puntos que cambian entre el tutorial y un despliegue real.

Los tres sumideros de tokens

El consumo de tokens en OpenClaw tiene tres fuentes de desperdicio que conviene conocer desde el inicio:

Historial completo en cada petición: OpenClaw envía todo el historial del hilo activo en cada llamada. Para hilos con semanas de historial, esto representa decenas de miles de tokens por mensaje. La solución es abrir hilos nuevos para temas distintos, no continuar siempre en el mismo.
Heartbeat mal calibrado: cada activación del Heartbeat es una llamada completa a la API con el contexto del sistema inyectado. Un Heartbeat cada 5 minutos con un contexto de 10.000 tokens puede costar varios euros al día sin hacer nada útil. Empieza con intervalos de 30 minutos mínimo.
Archivos de workspace sobredimensionados: AGENTS.md, SOUL.md y MEMORY.md se inyectan en cada turno. Si MEMORY.md crece sin control durante semanas, el coste base por petición aumenta de forma proporcional. Revisa y poda este archivo cada dos semanas.

Para tener visibilidad del consumo:

# Estado de uso actual con desglose por modelo
openclaw /usage full

# Ver el modelo activo en la sesión
openclaw /status

# Cambiar modelo durante una conversación
openclaw /model claude-haiku-4-5-20251001

Con un uso moderado (un workflow diario más consultas ocasionales) y usando Sonnet como modelo principal, el coste mensual debería estar entre 5 y 20 euros. Si superas eso en la primera semana, el Heartbeat o el tamaño de los hilos activos son los candidatos más probables.

Las técnicas de control de tokens en tiempo real que documenté para Claude Code aplican también aquí: el principio de medir antes de optimizar es el mismo independientemente del runtime.

Permisos y seguridad

OpenClaw puede ejecutar comandos de shell, leer archivos y llamar a APIs externas. Antes de darle permisos de escritura o ejecución, verifica su comportamiento durante al menos 48 horas en modo lectura. Para un despliegue en servidor, ejecutar el gateway con un usuario sin privilegios de sudo reduce el radio de impacto de cualquier error del agente.

Revisa siempre el objeto permissions en los metadatos de cada skill antes de instalarlo. Si un skill que no tiene relación con el sistema de archivos solicita fs.read_root o shell.execute, es una señal de alerta que requiere investigación antes de continuar. Para patrones de auditoría de skills, el artículo sobre skills de auditoría con memoria persistente tiene ejemplos aplicables directamente.

Backup del workspace

# Inicializar el workspace como repositorio git privado
cd ~/.openclaw/workspace
git init
git add AGENTS.md SOUL.md TOOLS.md IDENTITY.md USER.md HEARTBEAT.md
git commit -m "chore: initial workspace setup"

# Conectar a un repositorio privado (nunca público)
git remote add origin git@github.com:tu-usuario/openclaw-workspace.git
git push -u origin main

El workspace contiene preferencias y memoria acumulada durante semanas. Sin backup, perder el directorio significa empezar el onboarding desde cero. Trata estos archivos con el mismo cuidado que la configuración de producción de cualquier servicio crítico.

Errores comunes y depuración

Error: el agente responde de forma genérica e ignora el contexto del proyecto
Causa: los archivos de workspace están vacíos o con el contenido por defecto del wizard.
Solución: revisa el contenido de AGENTS.md y USER.md. Si están en blanco o con ejemplos genéricos, rellénlos con información real antes de continuar cualquier tarea.

Error: consumo de tokens muy alto sin realizar tareas complejas
Causa: Heartbeat con frecuencia alta o hilo de conversación con historial acumulado de semanas.
Solución: ejecuta openclaw /usage full para identificar el origen del consumo. Si es el Heartbeat, aumenta el intervalo. Si es el hilo activo, abre uno nuevo para empezar con contexto limpio.

Error: el agente ejecuta acciones no solicitadas
Causa: instrucciones ambiguas en AGENTS.md o límites de autonomía no definidos con suficiente precisión.
Solución: añade restricciones explícitas en AGENTS.md para las acciones que requieren confirmación. "Pedir confirmación antes de enviar mensajes a canales externos" es más efectivo que "ser cuidadoso con las acciones".

Error: el gateway no responde en localhost:3000
Causa: el daemon no está activo o falló en el arranque.
Solución: openclaw doctor reporta el estado del daemon y los problemas de configuración. Si el daemon no está activo, relánzalo con openclaw onboard --install-daemon.

Preguntas frecuentes

¿Cuánto tiempo lleva tener un workflow útil funcionando?

Con el setup correcto (archivos de workspace completos y un workflow concreto elegido desde el inicio), entre 2 y 4 horas desde la instalación. El error más común es invertir ese tiempo en exploración sin objetivo, lo que puede alargar el proceso varios días sin producir nada tangible.

¿Es necesario un servidor propio o funciona en local?

OpenClaw funciona en cualquier máquina con Node.js 22+, incluyendo un portátil o una Raspberry Pi. Para disponibilidad 24/7, un VPS pequeño (5-10 euros al mes) o un mini-PC dedicado son las opciones más habituales. MyClaw.ai ofrece instancias gestionadas si prefieres no mantener la infraestructura.

¿Qué pasa si MEMORY.md crece demasiado?

OpenClaw aplica límites internos que truncan el contenido de los archivos de workspace cuando superan el umbral configurado. Si MEMORY.md es demasiado grande, el agente puede perder contexto importante porque el archivo se corta antes de llegar a las secciones relevantes. Revisa y poda el archivo cada dos semanas, conservando solo lo que el agente necesita recordar a largo plazo.

El setup importa más que las features

OpenClaw tiene un ecosistema de skills, integraciones y capacidades que sigue creciendo. Ninguna feature compensa un workspace vacío. El agente es tan útil como el contexto que le das, y ese contexto se define en las primeras horas de configuración, no después de semanas de uso.

Las dos acciones con mayor impacto en los primeros días son configurar los archivos de workspace antes de pedir cualquier tarea, y elegir un workflow concreto con valor tangible como primer caso de uso real. El Heartbeat avanzado, los skills personalizados y la integración con APIs externas vienen después, cuando ya tienes algo que funciona.

Si ya tienes OpenClaw activo y quieres profundizar en flujos más complejos donde varios agentes se coordinan y revisan entre sí, el artículo sobre revisión cruzada entre agentes en producción es un buen siguiente paso. Y si estás pensando en diseñar pipelines que sobrevivan a caídas del proveedor de IA, los patrones de LLM fallback en automatizaciones son directamente aplicables a workflows de OpenClaw.

¿Qué workflow has configurado en tus primeras horas con OpenClaw? Cuéntamelo en los comentarios o en Twitter @sergiomarquezp_.