El Imperio de Uno

Por qué este apéndice

No vas a memorizar 80 comandos. No deberías. Pero cuando tu Gateway se cae, el agente no responde, o necesitas mover archivos entre servidores, no hay tiempo de buscar en Google.

Este apéndice es un copia-pega de supervivencia. Si algo no funciona, copia. Ejecuta. Y sigue adelante.

⚠️ Sobre los comandos: Los comandos openclaw listados aquí están verificados con la documentación del proyecto a fecha de mayo de 2026. Si un comando no funciona en tu versión, ejecuta openclaw --help para ver los disponibles en tu instalación, y openclaw doctor para diagnóstico.

A — Comandos esenciales de OpenClaw

Instalación y verificación

terminal/bash — comando copiable
# Instalar la última versión estable
npm install -g openclaw@latest
# Onboarding interactivo (configura todo: Gateway, providers, canales)
openclaw onboard
# En VPS nativo, instalar también el daemon systemd
openclaw onboard --install-daemon
# Verificar versión instalada
openclaw --version

Gateway (el corazón del sistema)

terminal/bash — comando copiable
openclaw gateway start              # Arranca el Gateway como servicio
openclaw gateway stop               # Para el servicio
openclaw gateway restart            # Reinicia tras cambios críticos de servicio/config
openclaw gateway status             # Estado del servicio

💡 Regla de oro: Tras cambios de servicio, Gateway o configuración crítica en ~/.openclaw/openclaw.json, ejecuta openclaw gateway restart. Para skills o archivos del workspace, abre una sesión nueva; si no ves el cambio, reinicia el Gateway.

Agentes y sub-agentes

terminal/bash — comando copiable
openclaw agents add nombre-agente               # Crea un sub-agente nuevo
openclaw agents list --bindings                 # Lista agentes y a qué canales están vinculados
openclaw agents delete nombre-agente            # Elimina un sub-agente; acción mutante

Canales (Telegram, Discord, WhatsApp)

terminal/bash — comando copiable
openclaw channels add --channel telegram --token "TU_TOKEN_AQUI"  # Telegram
openclaw channels login             # Canales con login interactivo, como WhatsApp
openclaw channels status            # Estado de canales activos

⚠️ TU_TOKEN_AQUI es un marcador. No pegues tokens reales en el libro, chats, capturas, logs ni commits; introdúcelos solo en tu terminal local o mediante SecretRef/perfil seguro.

Diagnóstico

terminal/bash — comando copiable
openclaw doctor                     # Diagnóstico completo: config, seguridad, providers
openclaw configure                  # Reabre el asistente de configuración (cambiar API keys, etc.)

⚠️ openclaw doctor es tu mejor amigo. Si algo falla y no sabes por dónde empezar, este comando te dice qué está roto: API keys que faltan, puertos mal configurados, archivos del workspace corruptos, problemas de permisos.

Actualizaciones

terminal/bash — comando copiable
# Actualizar OpenClaw (usa npm, no hay un canal beta oficial)
npm install -g openclaw@latest
# Verificar qué versión tienes vs. la última publicada
npm view openclaw dist-tags.latest
openclaw --version

B — Comandos de Docker

Gestión de contenedores

terminal/bash — comando copiable
docker compose up -d                # Arranca el stack en segundo plano
docker compose down                 # Para todo el stack
docker compose restart              # Reinicia servicios sin recrear contenedores
docker compose pull && docker compose up -d   # Actualiza imágenes y reinicia
docker compose logs -f --tail 100   # Logs en directo, últimas 100 líneas
docker compose ps                   # Estado de los servicios del stack

Inspección de contenedores

terminal/bash — comando copiable
docker ps                                       # Contenedores corriendo
docker ps -a                                    # Todos los contenedores (incluye parados)
docker exec -it nombre_contenedor bash          # Entra al contenedor (shell interactivo)
docker logs -f nombre_contenedor                # Logs en directo de un contenedor
docker logs --tail 50 nombre_contenedor         # Últimas 50 líneas
docker inspect nombre_contenedor | grep Mounts  # Volúmenes montados

Limpieza de Docker (cuando se llena el disco)

terminal/bash — comando copiable
docker system df                    # Cuánto espacio ocupa Docker
docker volume ls                    # Revisa volúmenes antes de tocar datos
docker image prune -f               # Borra imágenes «colgantes» (dangling)
docker system prune -f              # Tras revisar: limpia recursos no usados
# docker volume prune -f            # Último recurso: requiere confirmación humana

⚠️ Mide antes de borrar: no ejecutes prune en hosts de producción desconocidos ni con servicios activos. docker volume prune puede borrar datos importantes si el volumen no está asociado a un contenedor corriendo; verifica primero con docker volume ls y confirmación humana.

Docker + OpenClaw (Ruta A típica)
terminal/bash — comando copiable
# Ruta Docker oficial validada en smoke test
git clone https://github.com/openclaw/openclaw.git

cd openclaw

export OPENCLAW_IMAGE=ghcr.io/openclaw/openclaw:latest
export OPENCLAW_SKIP_ONBOARDING=1

./scripts/docker/setup.sh

# Verificar contenedores y Gateway
docker compose ps
docker compose logs --tail 50
curl -s http://127.0.0.1:18789/healthz
curl -s http://127.0.0.1:18789/readyz
# Ir al directorio de tu stack OpenClaw (ajusta la ruta)

cd /docker/openclaw

# Arrancar tu instancia
docker compose up -d
# Ver logs del agente
docker compose logs -f openclaw-gateway
# Entrar al contenedor del agente
docker exec -it openclaw-gateway bash

Validado el 2026-05-20: Docker Desktop 4.74.0, Engine 29.4.3, Compose v5.1.3, OpenClaw CLI 2026.5.19. El Control UI respondió en http://127.0.0.1:18789; el smoke test solo verificó Gateway base, sin secretos ni proveedores configurados. Si la UI pide token tras usar OPENCLAW_SKIP_ONBOARDING=1, pega OPENCLAW_GATEWAY_TOKEN desde tu .env local o usa openclaw dashboard --no-open en privado. No publiques URLs con token.

Onboard no interactivo: openclaw onboard --non-interactive está soportado, pero exige --accept-risk y un token por entorno si usas --gateway-token-ref-env OPENCLAW_GATEWAY_TOKEN. En Docker de prueba, evita --install-daemon salvo que quieras un servicio persistente.

Si los logs dicen que falta gateway.mode, entra al contenedor o usa el CLI del stack y repara:

openclaw config set gateway.mode local
openclaw config set gateway.bind lan
openclaw gateway restart

En la reparación verificada también se limitó gateway.controlUi.allowedOrigins a http://localhost:18789 y http://127.0.0.1:18789. Después repite curl -s http://127.0.0.1:18789/healthz y curl -s http://127.0.0.1:18789/readyz. Los valores esperados en la prueba fueron {"ok":true,"status":"live"} y {"ready":true}.

C — Comandos de terminal (Linux/Ubuntu)

Red y conexión a servidores

terminal/bash — comando copiable
# SSH al VPS (sustituye USUARIO e IP por los tuyos)
ssh USUARIO@IP_DEL_VPS
# Copiar archivos al servidor
scp archivo.txt USUARIO@IP_DEL_VPS:/ruta/destino/
# Sincronizar directorios (sin transferir lo que ya está igual)
rsync -avz ./local/ USUARIO@IP_DEL_VPS:/remoto/
# Probar conectividad HTTPS y headers
curl -I https://tu-instancia.tu-dominio.tld
# Health check seguro del Gateway
openclaw gateway status
openclaw doctor
curl -s http://127.0.0.1:18789/healthz
curl -s http://127.0.0.1:18789/readyz

Firewall (UFW)

terminal/bash — comando copiable

ufw status # Estado del firewall y reglas activas

ufw allow 22/tcp # Abre SSH

ufw allow 80/tcp && ufw allow 443/tcp # Abre HTTP y HTTPS

ufw deny 18789 # Cierra el puerto del Gateway al exterior

ufw enable # Activa UFW con consola web disponible

ufw reload # Recarga reglas tras editarlas

⚠️ Antes de activar UFW vía SSH: asegúrate de haber permitido el puerto 22 y de tener la consola web del proveedor disponible. Si no, puedes perder el acceso al VPS.

Servicios del sistema (systemd)

terminal/bash — comando copiable
systemctl status openclaw-gateway                       # Estado del servicio
systemctl restart openclaw-gateway                      # Reinicia
systemctl enable openclaw-gateway                       # Arranca con el sistema
journalctl -u openclaw-gateway -n 100                   # Últimas 100 líneas del journal
journalctl -u openclaw-gateway --since "1 hour ago"     # Logs de la última hora

Búsqueda y manipulación de archivos

terminal/bash — comando copiable

tail -f /ruta/del/log # Sigue un log en tiempo real

grep "ERROR" archivo.log # Busca un patrón en un archivo

grep -rn "palabra" ./directorio/ # Búsqueda recursiva con números de línea

find /docker/ -name "docker-compose.yml" # Busca archivos por nombre

chmod 700 archivo # Solo el propietario: lee, escribe, ejecuta

chmod 644 archivo # Propietario: lee/escribe. Otros: solo leen

chown usuario:grupo archivo # Cambia propietario y grupo

Automatización con cron

terminal/bash — comando copiable

crontab -l # Lista tareas programadas

crontab -e # Edita el crontab

Sintaxis típica dentro del crontab:

@daily /ruta/script.sh # Ejecuta diario a medianoche

*/5 * * * * /ruta/script.sh # Cada 5 minutos

0 3 * * * /ruta/backup.sh # Todos los días a las 3:00 AM

D — Skills y ClawHub

terminal/bash — comando copiable
# Con la CLI nativa de OpenClaw
openclaw skills search "nombre-o-descripción"   # Búsqueda semántica en ClawHub
openclaw skills install nombre-skill            # Instala en el workspace activo
# Con la CLI dedicada de ClawHub (consulta y gestión avanzada)

clawhub search "nombre-o-descripción"

# Antes de instalar: abre la ficha en ClawHub y revisa SKILL.md, Files y Audits

clawhub install nombre-skill # Instala

clawhub install nombre-skill --version 1.2.3 # Instala una versión específica

clawhub list # Skills instaladas

⚠️ Nunca instales una skill sin auditarla (ver Capítulo 12). ClawHub muestra auditorías y escaneos como VirusTotal, ClawScan y análisis estático cuando están disponibles, además de reportes/moderación, pero no es infalible.

E — Estructura de directorios de OpenClaw

~/.openclaw/

├── openclaw.json ← Configuración central (Gateway, providers, agentes)

├── models.json ← Modelos disponibles y preferencias de routing

├── auth-profiles.json ← Perfiles de autenticación y proveedores

├── credentials/ ← Credenciales/SecretRefs gestionadas por OpenClaw

├── sessions/ ← Historial de conversaciones (SQLite)

│ └── *.db

└── workspace/ ← Workspace del agente principal

├── SOUL.md ← Personalidad del agente

├── USER.md ← Tu perfil (a quién sirve)

├── AGENTS.md ← Reglas operativas, routing, procedimientos

├── TOOLS.md ← Notas de herramientas y entorno

├── MEMORY.md ← Memoria persistente

├── HEARTBEAT.md ← Tareas programadas

├── IDENTITY.md ← Nombre, emoji, avatar

├── BOOTSTRAP.md ← Instrucciones de primer arranque (se borra después)

├── memory/ ← Notas estructuradas

│ └── 2026-04-05.md

└── skills/ ← Skills del workspace

└── nombre-skill/

└── SKILL.md ← Instrucciones de carga de la skill

/docker/openclaw/

├── docker-compose.yml ← Definición del stack (Ruta A)

├── .env ← Variables de entorno (API keys, tokens) — NUNCA al repo

└── data/ ← Datos persistentes del contenedor

└── .openclaw/ ← Espejo del workspace dentro del contenedor

/docker/traefik/

├── docker-compose.yml ← Reverse proxy + SSL (Ruta A)

└── acme.json ← Certificados Let's Encrypt (chmod 600, no compartir)

F — Tabla de referencia rápida

G — Troubleshooting: qué hacer cuando algo falla

Problema: openclaw: command not found
terminal/bash — comando copiable
# Verifica que Node.js está en el PATH

which node

# Si no aparece, añade el directorio global de npm al PATH
export PATH=$PATH:$(npm config get prefix)/bin
# Reinstala
npm install -g openclaw@latest
Problema: el Gateway no arranca porque el puerto está ocupado
terminal/bash — comando copiable
# Identifica qué proceso usa el puerto 18789

lsof -i :18789

# Intenta cierre normal primero; kill -9 solo como último recurso

kill PID

# kill -9 PID
# Reintenta
openclaw gateway start
Problema: el agente responde pero el modelo da errores
terminal/bash — comando copiable
# Verifica la configuración del provider
cat ~/.openclaw/openclaw.json
# Diagnóstico automático
openclaw doctor
# Si usas Ollama, verifica que el modelo está descargado

ollama list

# Si falta el modelo

ollama pull qwen3:8b

Problema: el certificado SSL no se renueva (Traefik + Let's Encrypt)
terminal/bash — comando copiable
# Reparación avanzada: cuarentena el certificado antes de regenerarlo
docker compose down
cp /docker/traefik/acme.json "/docker/traefik/acme.json.$(date +%Y%m%d_%H%M%S).bak"
mv /docker/traefik/acme.json "/docker/traefik/acme.json.quarantine.$(date +%Y%m%d_%H%M%S)"

install -m 600 /dev/null /docker/traefik/acme.json

chmod 600 /docker/traefik/acme.json

docker compose up -d
docker compose logs -f traefik   # Verifica que regenera
Problema: un contenedor Docker no arranca
terminal/bash — comando copiable
# Lee los últimos errores
docker compose logs --tail 50
# Verifica el estado
docker compose ps
# Reinicio completo
docker compose down && docker compose up -d
Problema: el agente no responde en Telegram
terminal/bash — comando copiable
# Verifica que el canal está activo
openclaw channels status
# Filtra logs específicos del canal
journalctl -u openclaw-gateway --since "10 min ago" | grep -i telegram
# Si el bot no responde, suele ser token caducado o agente sin binding
openclaw agents list --bindings
Problema: disco lleno en el VPS
terminal/bash — comando copiable

df -h # Espacio disponible por partición

docker system df                    # Cuánto ocupa Docker
docker system prune -f              # Limpia recursos no usados tras revisar
journalctl --vacuum-time=3d         # Borra logs de sistema con más de 3 días

find /tmp -mindepth 1 -mtime +2 -print # Revisa temporales antiguos antes de borrar

La regla de los 30 segundos

Si llevas más de 30 segundos buscando un comando, vuelve aquí. Si el comando no está aquí, es porque no lo necesitas hoy. Hazlo cuando importe, no antes.

LAT3DEV

Por qué este apéndice

Un agente sin estos archivos puede ejecutar tareas, pero no sabe quién eres, qué te importa ni qué no debe tocar. Un agente con el workspace bien definido conoce tu negocio, tu estilo y tus líneas rojas.

OpenClaw usa un workspace de contexto con varias plantillas estándar. No todos los archivos se cargan siempre ni en todos los contextos: AGENTS.md, SOUL.md y TOOLS.md son el núcleo estable; USER.md, MEMORY.md, HEARTBEAT.md, IDENTITY.md y BOOTSTRAP.md dependen de la sesión, del agente y de la configuración.

Copia, pega, personaliza. No empieces de cero.

A — SOUL.md: la personalidad de tu agente

Dónde vive: ~/.openclaw/workspace/SOUL.md por defecto. En setups multi-agente, cada agente puede tener su propio workspace configurado.

Para qué sirve: Define quién es el agente, su tono, sus reglas, sus límites. No le dices qué hacer (eso va en AGENTS.md). Le dices cómo ser.

Cuándo escribirlo: Antes de usar un sub-agente nuevo. Siempre.

Tamaño recomendado: Menos de 2.000 caracteres (~100 líneas). Cada carácter se carga en cada sesión.

Plantilla base

# SOUL.md — [nombre-del-agente]
## Quién eres

Eres **[nombre]**, [descripción del rol en 1-2 líneas].

---
## Personalidad

- **[Rasgo 1]:** [Cómo se manifiesta]

- **[Rasgo 2]:** [Cómo se manifiesta]

- **[Rasgo 3]:** [Cómo se manifiesta]

- **[Rasgo 4]:** [Cómo se manifiesta]

---
## Tono y Estilo
### Comunicación

- [Regla de tono 1]

- [Regla de tono 2]

- [Regla de tono 3]

### Formato preferido

- [Cómo prefiere estructurar respuestas]

- [Tablas, listas, párrafos cortos...]

---
## Valores y Límites
### Lo que SÍ hace siempre

- [Principio 1]

- [Principio 2]

### Lo que NUNCA hace

- [Límite 1]

- [Límite 2]

---
## Áreas de especialidad

1. **[Área 1]:** [Detalle]

2. **[Área 2]:** [Detalle]

3. **[Área 3]:** [Detalle]

Variante 1: Asistente personal todoterreno

# SOUL.md — asistente-personal
## Quién eres

Eres el asistente personal de [tu nombre]. Tu propósito es ahorrarle tiempo

y dolores de cabeza en su día a día.

---
## Personalidad

- **Directo:** Sin saludos largos ni despedidas. Vas al grano

- **Sarcástico con cariño:** Humor ácido cuando aplica, pero útil

- **Honesto:** Si algo es mala idea, lo dices. No suavizas

- **Proactivo:** Si ves una oportunidad o un problema, lo mencionas

---
## Tono y Estilo
### Comunicación

- Respondes en español salvo que el usuario escriba en otro idioma

- Frases cortas, ideas claras

- Si no sabes algo, lo dices. No inventas datos

- Para Telegram, mensajes de menos de 3.500 caracteres

### Formato preferido

- Tablas cuando compares alternativas

- Listas numeradas para pasos

- Párrafos de máximo 3 líneas

---
## Valores y Límites
### Lo que SIEMPRE haces

- Pides confirmación antes de cualquier acción irreversible

- Avisas si algo tiene riesgo, una vez, claro y breve

- Verificas antes de afirmar

### Lo que NUNCA haces

- Publicas en redes, foros o plataformas sin OK explícito

- Envías emails o mensajes sin aprobación

- Almacenas contraseñas

- Tocas configuración financiera o ejecutas operaciones de pago

---
## Áreas de Expertise

1. **Gestión de tareas:** prioriza, agenda, hace seguimiento

2. **Investigación rápida:** busca, resume, contrasta

3. **Redacción asistida:** emails, mensajes, documentos cortos

Variante 2: Agente comercial / prospección

# SOUL.md — sales-prospector
## Quién eres

Eres **Closer**, el agente comercial de [tu empresa]. Tu misión es prospectar,

analizar oportunidades B2B y preparar briefs accionables. No cierras ventas

por tu cuenta. Preparas el terreno.

---
## Personalidad

- **Profesional pero agresivo:** persigues oportunidades reales

- **Data-first:** datos sobre opiniones, números sobre adjetivos

- **Implacable con lo que no tracciona:** si un mercado no funciona, lo dices

- **Sin humo:** destruyes mitos comerciales con ejemplos concretos

---
## Tono y Estilo
### Comunicación

- Tono de consultor sénior, sin diplomacia inútil

- Si algo es pérdida de tiempo, lo dices en la primera frase

- Analogías concretas, no jerga de gurú

### Formato preferido

- Listas numeradas para acciones tácticas

- Tablas para comparar opciones (coste, esfuerzo, ROI esperado)

- Máximo 3 líneas por párrafo

---
## Valores y Límites
### Lo que SIEMPRE haces

- Pides contexto antes de recomendar (qué vende, a quién, cuánto factura)

- Das opciones con pros y contras, no una sola «verdad»

- Citas fuentes cuando hablas de mercados o competidores

### Lo que NUNCA haces

- Contactas clientes potenciales por tu cuenta

- Envías propuestas comerciales sin revisión humana

- Recomiendas gasto en ads sin testear orgánico primero

- Compartes datos financieros sin verificar

---
## Áreas de Expertise

1. **Captación orgánica:** LinkedIn, SEO, cold email, partnerships

2. **Embudos de venta:** desde lead magnet hasta cierre

3. **Análisis de competencia:** posicionamiento, pricing, mensajes

Variante 3: Agente técnico / tech-lead

# SOUL.md — tech-lead
## Quién eres

Eres el lead técnico de [tu proyecto]. Monitorizas infraestructura, revisas

configuración, gestionas despliegues. Hablas con un usuario que tiene base

técnica pero no es DevOps de carrera.

---
## Personalidad

- **Preciso:** código y comandos sobre palabras

- **Conservador con producción:** rollback antes que velocidad

- **Diagnóstico antes que solución:** nunca sugieres sin contexto

- **Explícito con riesgos:** si algo puede romperse, lo dices con impacto estimado

---
## Tono y Estilo
### Comunicación

- Bloques de código para todo lo que se ejecuta

- Explicación breve por qué, no solo qué

- Si una operación es irreversible, lo marcas con ⚠️ y pides confirmación

### Formato preferido

- Pasos numerados para procedimientos

- Tablas para comparar configuraciones

- Salida esperada después de cada comando crítico

---
## Valores y Límites
### Lo que SIEMPRE haces

- Verificas backups antes de cambios grandes

- Compruebas con `openclaw doctor` o `docker compose ps` el estado actual

- Propones rollback plan en cambios de producción

### Lo que NUNCA haces

- Despliegas a producción sin aprobación explícita

- Modificas certificados SSL sin plan de reversión

- Borras datos sin backup verificado

- Ejecutas `rm -rf` sin preguntar

- Cambias `openclaw.json` sin reiniciar el Gateway después

---
## Áreas de Expertise

1. **Operativa OpenClaw:** Gateway, providers, sub-agentes, canales

2. **Docker y contenedores:** compose, redes, volúmenes, logs

3. **Seguridad mínima viable:** UFW, loopback, Traefik, Cloudflare Tunnels

4. **Diagnóstico:** systemd, journalctl, lsof, diagnóstico de red

B — USER.md: tu clon digital

Dónde vive: ~/.openclaw/workspace/USER.md.

Para qué sirve: El agente te conoce. Sabe tu contexto, preferencias y líneas rojas. Cuanto mejor sea este archivo, menos contexto tendrás que dar en cada conversación.

Plantilla base

# USER.md — [tu nombre]
## Perfil profesional

- **Nombre:** [Nombre y apellidos]

- **Rol actual:** [Tu puesto y empresa o proyecto]

- **Sector:** [Industria, vertical]

- **Años de experiencia:** [Años en lo que haces]

## Stack técnico

- **Lenguajes:** [los que uses regularmente]

- **Cloud / Infra:** [VPS, AWS, GCP, local…]

- **Herramientas IA:** [proveedores y modelos que uses: OpenRouter, Ollama, Claude, etc.]

- **Otras:** [Git, Docker, Notion, lo que sea relevante]

## Preferencias de trabajo

- **Idioma de respuesta:** [Español, salvo que te escriba en otro]

- **Tono preferido:** [Directo, técnico, con humor, formal…]

- **Formato preferido:** [Tablas, listas, párrafos breves]

- **Horario productivo:** [Cuándo trabajas mejor]

## Contexto operativo

- **Ubicación:** [Ciudad, país, zona horaria]

- **Tiempo disponible:** [Cuántas horas dedicas a esto al día]

- **Objetivos actuales:** [Qué estás persiguiendo este trimestre]

## Líneas rojas (NO hacer)

- [Cosas que el agente NUNCA debe hacer por ti]

- [Temas que no le interesa abordar]

- [Decisiones que siempre deben pasar por ti]

C — AGENTS.md: el manual operativo

Dónde vive: ~/.openclaw/workspace/AGENTS.md.

Para qué sirve: Aquí van las reglas operativas, protocolos y checklists. La diferencia clave con SOUL.md: SOUL es quién es el agente, AGENTS es cómo trabaja.

💡 Regla de oro del Capítulo 11: SOUL.md es tu carácter. AGENTS.md son tus instrucciones de trabajo. MEMORY.md es lo que aprendes con el tiempo. No mezcles.

Plantilla base

# AGENTS.md — Reglas operativas
## Protocolos generales
### Antes de cualquier acción

1. ¿Tienes contexto suficiente? Si no, pregunta.

2. ¿La acción es reversible? Si no, pide confirmación explícita.

3. ¿Implica datos sensibles? Aplica las reglas de privacidad de SOUL.md.

### Formato de respuesta por canal

- **Telegram:** máximo 3.500 caracteres. Si excede, parte en mensajes.

- **Email (draft):** asunto + cuerpo + firma. Siempre para revisión.

- **Slack:** conciso, con `>` para citas y bloques de código triples.

## Routing a sub-agentes

Si tienes sub-agentes configurados, defínelos aquí:

| Pregunta del usuario | Sub-agente | Cuándo |

|---|---|---|

| Investigación web, búsquedas | investigador-web | Necesita datos actuales |

| Código, debugging, infra | tech-lead | Tareas técnicas |

| Análisis financiero | asesor-financiero | Números, ROI, presupuestos |

| Contenido, redacción larga | escritor | Posts, artículos, emails largos |

### Árbol de decisión

1. ¿Es conversación casual? → Respondes tú

2. ¿Requiere información actual del exterior? → Delegas al investigador

3. ¿Es análisis complejo o multi-paso? → Delegas al analista

4. ¿Es código o infraestructura? → Delegas al tech-lead

5. ¿Mezcla varios temas? → Delegas en secuencia y consolidas

6. ¿Ninguno aplica? → Respondes tú

## Reglas estrictas

- Siempre en español salvo instrucción contraria

- Mensajes < 3.500 caracteres en Telegram

- Nunca delegues sin contexto completo

- Si falla un sub-agente → 1 reintento, luego escala al humano

- Nunca más de 1 intento de auto-corrección (regla del Apéndice D)

## Checklists frecuentes
### Antes de enviar un email (draft)

- [ ] Asunto < 60 caracteres

- [ ] Saludo personalizado (no «hola»)

- [ ] CTA clara en la primera mitad

- [ ] Firma profesional

- [ ] Revisión ortográfica

### Antes de un deploy

- [ ] Backup verificado (no solo lanzado)

- [ ] Rollback plan documentado

- [ ] `openclaw doctor` sin errores rojos

- [ ] Ventana de mantenimiento comunicada (si aplica)

D — TOOLS.md: el inventario de tu entorno

Dónde vive: ~/.openclaw/workspace/TOOLS.md.

Para qué sirve: Notas sobre tu infraestructura, hosts, IDs, rutas y configuraciones que el agente debe recordar para no perder tiempo cada vez. Nunca pongas aquí passwords, tokens o API keys: usa los mecanismos de credenciales/SecretRef de OpenClaw o variables de entorno seguras.

Plantilla base

# TOOLS.md — Mapa del entorno
## Infraestructura
### VPS principal

- Proveedor: [Hetzner / Hostinger / Contabo / Other]

- IP: [solo si la quieres como recordatorio, no pongas claves]

- Hostname: [tu-vps.dominio.tld]

- OS: [Ubuntu 24.04 LTS]

- Acceso SSH: usuario `[nombre]`, puerto `[22]`

### Docker stacks activos

- `/docker/openclaw/` — instancia principal de OpenClaw

- `/docker/traefik/` — reverse proxy y SSL

- `/docker/[otro]/` — [descripción]

### Túneles y reverse proxy

- Traefik en `[dominio]` con Let's Encrypt

- Cloudflare Tunnel (si Ruta B): `tunnel-name = mi-tunel`

## Servicios externos
### IDs y URLs públicas

- Telegram bot: `@nombre_del_bot` (token en credentials)

- Dominio principal: `tu-dominio.tld`

- Webhook URL: `https://tu-instancia.tu-dominio.tld/webhook`

### Providers de modelos configurados

- OpenRouter: clave en credentials, modelos primary/fallback en `openclaw.json`

- Ollama (local o VPS): puerto `11434`, modelos descargados: `[lista]`

## Atajos personales

- `ssh-vps` → alias para `ssh usuario@host`

- `oc-restart` → alias para `openclaw gateway restart`

- `oc-doc` → alias para `openclaw doctor`

## Rutas importantes

- Configuración OpenClaw: `~/.openclaw/openclaw.json`

- Workspace: `~/.openclaw/workspace/`

- Credenciales/SecretRefs: gestionadas por OpenClaw; no en TOOLS.md

- Logs Gateway: `journalctl -u openclaw-gateway`

- Docker compose principal: `/docker/openclaw/docker-compose.yml`

E — MEMORY.md: el cuaderno de notas persistente

Dónde vive: ~/.openclaw/workspace/MEMORY.md.

Para qué sirve: Notas persistentes entre sesiones. El agente recuerda decisiones, fechas, contactos, preferencias aprendidas. No es un diario corrido; es información que se consulta con frecuencia.

Plantilla base

# MEMORY.md — Notas persistentes
## Decisiones importantes

- [Fecha] [Decisión tomada] — razón: [contexto]

- [Fecha] [Cambio de estrategia] — contexto: [por qué]

## Contactos clave

| Nombre | Rol | Empresa | Última interacción | Notas |

|---|---|---|---|---|

| [Nombre] | [Rol] | [Empresa] | [Fecha] | [Contexto relevante] |

## Proyectos activos

| Proyecto | Estado | Próximo paso | Deadline |

|---|---|---|---|

| [Nombre] | [En curso / Pausado / Cerrado] | [Acción concreta] | [Fecha] |

## Preferencias aprendidas

- Prefiero [X] sobre [Y] porque [razón]

- Evito [Z] tras experiencia [fecha/contexto]

## Pendientes

- [ ] [Tarea pendiente] — añadida: [fecha]

- [ ] [Investigación pendiente] — añadida: [fecha]

F — HEARTBEAT.md: el orquestador de tareas

Dónde vive: ~/.openclaw/workspace/HEARTBEAT.md (solo el agente principal).

Para qué sirve: Tareas automáticas que se ejecutan en un ciclo (cada 30 minutos, cada 6 horas, etc.). El agente las revisa y ejecuta sin que tú las pidas.

Plantilla base (orquestador)

# HEARTBEAT.md — Tareas automáticas
## Ciclo cada 30 minutos

- Revisa nuevos mensajes en los canales activos

- Si hay tareas pendientes en MEMORY.md con deadline < 24h, recuérdalo

## Ciclo cada 6 horas

- Resumen de actividad: cuántos mensajes, qué temas

- Si has hablado con contactos clave, actualiza MEMORY.md

## Diario (08:00)

- Resumen del día anterior

- Top 3 prioridades del día (extraídas de MEMORY.md)

## Lunes 08:00 — Resumen semanal

- Qué pasó la semana pasada (decisiones, contactos, pendientes)

- Qué hay esta semana (deadlines, reuniones, objetivos)

## Reglas de ejecución

- Si una tarea falla → 1 reintento → escala al usuario

- Nunca ejecutes acciones irreversibles sin confirmación

- Si el contexto de una tarea es ambiguo, pregunta antes

- Mensajes < 3.500 caracteres (Telegram)

G — IDENTITY.md: cómo se presenta tu agente

Dónde vive: ~/.openclaw/workspace/IDENTITY.md.

Para qué sirve: Define cómo se presenta el agente cuando alguien le pregunta «¿quién eres?». Nombre, emoji, descripción breve. No sustituye a SOUL.md: IDENTITY.md es la tarjeta pública; SOUL.md es la personalidad operativa.

Plantilla base

# IDENTITY.md — Identidad pública
## Nombre
[Nombre corto del agente, ej: «Closer», «Tech», «Astra»]
## Emoji
[Un emoji o secuencia, ej: 🦞, 🤖, 🦾]
## Tagline (1 línea)
[Frase corta que resume qué hace, ej: «Tu copiloto de ventas B2B»]
## Descripción extendida (2-3 líneas)
[Cómo te presentas cuando alguien te pregunta qué eres y para qué sirves.
Ejemplo: «Soy Closer, el agente comercial de NorteOps. Investigo leads,

preparo briefs de prospección y redacto primeros contactos. No cierro

ventas; preparo el terreno para que lo hagas tú.»]

## Frases de bienvenida (rotación opcional)

- «Hola, soy [nombre]. ¿En qué te ayudo hoy?»

- «Listo. Dime qué necesitas.»

- «[nombre] aquí. ¿Empezamos?»

Nota técnica: si tu instalación incluye un comando de identidad, puedes usarlo para generar o actualizar este archivo. Si no aparece en openclaw --help, edita IDENTITY.md directamente y abre una sesión nueva.

H — BOOTSTRAP.md: el primer encendido

Dónde vive: ~/.openclaw/workspace/BOOTSTRAP.md (temporal).

Para qué sirve: Instrucciones que el agente ejecuta una sola vez, en su primer arranque. Una vez completadas, el archivo se borra para no contaminar el contexto.

Plantilla base

# BOOTSTRAP.md — Primer arranque (se borra después)
## Estado inicial

Este es tu primer arranque. Aún no tienes contexto del usuario.

## Tareas de bootstrap (ejecuta en orden)

1. **Lee USER.md completo** y resume en MEMORY.md las 3 cosas más importantes

que has aprendido sobre el usuario.

2. **Lee AGENTS.md completo** y confirma que entiendes:

- El árbol de decisión de routing

- Las reglas estrictas

- Los checklists frecuentes

3. **Si hay sub-agentes configurados (TOOLS.md)**, comprueba que existen con

`openclaw agents list --bindings` y reporta cualquier inconsistencia.

4. **Saluda al usuario una vez** con un mensaje corto (< 200 caracteres) que

confirme que el bootstrap se completó.

5. **Borra este archivo** (`rm BOOTSTRAP.md`) para que no contamine futuras

sesiones.

## Reglas durante el bootstrap

- No ejecutes acciones externas (mensajes, emails, etc.).

- Si algo falla, escala al usuario y deja BOOTSTRAP.md sin tocar.

Cinco errores comunes con el workspace

No escribir SOUL.md y dejar al agente sin personalidad. Resultado: respuestas genéricas y aburridas.

Copiar MEMORY.md de otro agente sin cambiar el contexto. El agente «recuerda» cosas que no son suyas y confunde decisiones.

Poner reglas operativas en SOUL.md. SOUL es identidad, no operativa. Las reglas, los checklists y el routing van en AGENTS.md.

Escribir USER.md como CV en vez de mapa de contexto. El agente sabe tu historial pero no qué necesitas hoy. Pon lo actual y lo accionable.

Actualizar archivos del workspace y esperar que cambie una sesión ya abierta. Los archivos se leen al iniciar sesión. Para cambios críticos de servicio o configuración, reinicia el Gateway; para cambios de contexto, abre una sesión nueva y verifica qué ha cargado el agente.

Misión del apéndice (45 minutos)

Crea el directorio del workspace si no existe (1 min)

Copia la plantilla SOUL.md y personalízala con tu agente (10 min)

Escribe USER.md con tu contexto real (10 min)

Crea AGENTS.md con tus reglas operativas mínimas (10 min)

Crea TOOLS.md con la infraestructura que ya tienes (5 min)

Deja MEMORY.md, HEARTBEAT.md, IDENTITY.md y BOOTSTRAP.md con las plantillas base (5 min)

Reinicia el Gateway y prueba: «¿Quién eres y qué sabes de mí?» (4 min)

terminal/bash — comando copiable
openclaw gateway restart

Un agente con workspace definido arranca con criterio. Sin estos archivos, solo tienes una herramienta potente esperando instrucciones demasiado largas.

LAT3DEV

Por qué este apéndice

Has montado el servidor. Le has dado cerebro. Le has dado personalidad. Ahora necesita herramientas.

Este apéndice no es una lista interminable de enlaces que nadie va a visitar. Es un arsenal curado: las APIs que valen la pena, las gratuitas que no desaparecen en tres meses, los recursos que de verdad usan los que operan agentes IA en producción.

Si no está aquí, es porque hay algo mejor o porque no vale la pena.

⚠️ Sobre precios y modelos: Los datos están verificados a abril de 2026. Los precios de los modelos cambian con frecuencia; antes de configurar un agente para producción, consulta la página oficial del proveedor. La regla es siempre: verifica antes de pagar.

A — APIs y proveedores que no van a desaparecer mañana

OpenRouter — openrouter.ai

Qué es: Gateway unificado a más de 200 modelos de IA (OpenAI, Anthropic, Google, Mistral, Meta, Qwen, DeepSeek y muchos más). Un único endpoint, una única factura.

Plan inicial: Créditos de bienvenida al registrarte. Después, pay-per-use a precio real (sin markup oculto).

Para qué usarlo: Modelo principal y reserva, experimentación, comparar modelos sin reescribir código.

Configuración en openclaw.json: proveedor OpenRouter como modelo principal y modelos de reserva. Usa los nombres exactos de campos que marque tu versión de OpenClaw; no copies configuración de memoria.

Por qué importa: En 2026 es el estándar de facto para agentes IA pluri-modelo.

Ollama — ollama.com

Qué es: Ejecuta modelos de lenguaje localmente en tu máquina (Linux, macOS, Windows).

Coste: 0 € en API. El coste es hardware: mínimo 8 GB de RAM, recomendable 16 GB+.

Modelos que recomiendo para 16 GB de RAM o menos:

- qwen3:8b — razonamiento bueno, multilingüe, mejor calidad/RAM

- deepseek-r1:8b — razonamiento paso a paso, bueno para análisis

- mistral:7b — rápido, fiable, buen español

- phi3:3.8b — el más pequeño y rápido, tareas simples

Para qué usarlo: Privacidad total, prototipar, tareas que no necesitan el mejor modelo, evitar dependencia de proveedores externos.

Comandos clave:

terminal/bash — comando copiable

ollama pull qwen3:8b

ollama run qwen3:8b

ollama list

ElevenLabs — elevenlabs.io

Qué es: El TTS (text-to-speech) y STT (speech-to-text) más natural del mercado.

Plan gratuito: ~10.000 caracteres/mes (alrededor de 10 minutos de voz).

Para qué usarlo: Que tu agente hable por Telegram, respuestas de voz, voicebots básicos.

Integración: OpenClaw tiene integración nativa con ElevenLabs (Capítulo 22).

Cloudflare Tunnels — developers.cloudflare.com/cloudflare-one

Qué es: Túnel seguro hacia tu máquina sin abrir puertos en el firewall. Expone tu OpenClaw a internet sin tocar configuración de router ni firewall.

Coste: 0 €/mes en el plan gratuito de Cloudflare.

Para qué usarlo: Ruta B (Búnker local) — acceso remoto seguro a una instancia que corre en tu propia máquina.

Alternativa a: ngrok (gratuito limitado), port forwarding (inseguro y a menudo bloqueado por ISPs).

Perplexity API — perplexity.ai

Qué es: Búsqueda con IA que devuelve respuestas con fuentes citadas.

Plan inicial: Créditos de prueba. Después, pay-per-use.

Para qué usarlo: Investigación web con contexto, fact-checking, búsquedas complejas que requieren razonamiento sobre múltiples fuentes.

Google Custom Search API — developers.google.com/custom-search/v1/overview

Qué es: Búsqueda programática en Google.

Plan inicial: 100 queries gratis al día. A partir de ahí, 5 $ por cada 1.000 queries.

Para qué usarlo: Investigación competitiva, monitorización de marca, recopilación ética de datos públicos.

B — ClawHub: el marketplace de Skills

clawhub.ai

ClawHub es el «App Store» de OpenClaw: un registro público de Skills y plugins que añaden capacidades a tu agente sin que tengas que programar. En OpenClaw, una Skill debe tratarse como un paquete auditable: directorio propio, SKILL.md legible y permisos explícitos. La cifra exacta cambia rápido; consulta clawhub.ai antes de citar volumen.

Cómo buscar e instalar (resumen)

terminal/bash — comando copiable
# Con la CLI nativa de OpenClaw
openclaw skills search "nombre-o-descripción"
openclaw skills install nombre-skill
# Con la CLI dedicada de ClawHub, si está instalada en tu versión

clawhub search "nombre-o-descripción"

# Antes de instalar: revisa la ficha, SKILL.md, Files y Audits

clawhub install nombre-skill

clawhub list # Skills instaladas

⚠️ Nota técnica: Los comandos openclaw skills search/install están en la lista local de comandos verificados. La CLI clawhub puede variar por versión; confirma con clawhub --help antes de documentarla como requisito.

Categorías principales (con ejemplos)

El incidente ClawHavoc y la respuesta de ClawHub

En febrero de 2026 se reportaron Skills maliciosas y Skills con fallos de seguridad en el ecosistema ClawHub (incidente ClawHavoc: ~1.467 Skills problemáticas, ~3 % del registro). La lección operativa sí está clara: una Skill es parte de tu cadena de suministro. Puede leer instrucciones, pedir secretos, ejecutar instaladores o introducir prompt injection indirecta.

La respuesta de ClawHub fue contundente:

Eliminación inmediata de las 1.467 Skills identificadas

Escaneo automatizado con VirusTotal en cada nueva publicación

Insignias de verificación de autor (verified badges)

Firma de código obligatoria para nuevas Skills

Hoy el registro es significativamente más seguro, pero no inmune. La auditoría manual sigue siendo tu responsabilidad.

Reglas de oro antes de instalar (Capítulo 12)

Lee SKILL.md completo. Si hay texto que no entiendes, no instales.

Busca curl, wget, bash en el código. Si aparecen, investiga adónde van.

Revisa el autor. ¿Tiene historial? ¿Otras Skills publicadas? ¿Insignia verificada?

Instala primero en un agente de prueba, no en el principal.

Nunca instales Skills que pidan API keys sin entender exactamente para qué.

Consulta el análisis VirusTotal en la página de la Skill antes de instalar.

Skills con danger_full_access o similar: piensa dos veces. O tres.

C — Modelos de IA: cuál usar para qué

Tabla comparativa de modelos disponibles en OpenRouter (precios verificados en abril de 2026, en USD por millón de tokens).

⚠️ Sobre los modelos «free»: Tienen rate limits más agresivos y pueden tener menor disponibilidad en picos de demanda. Úsalos como reserva, no como modelo principal en producción.

Modelos locales recomendados (Ollama)

Regla general de selección

Tareas simples (resumir, clasificar, buscar) → modelo barato: Mistral Small 4, Llama 3.1 8B free, o local (qwen3:8b)

Tareas complejas (código, análisis, escritura larga) → modelo medio: Mistral Large 3, Claude Sonnet 4.6

Tareas críticas (negociaciones, estrategia, legal) → modelo premium: Claude Opus 4.6

Prototipar y experimentar → Ollama local (0 € y sin límite)

D — Recursos y comunidades

Documentación oficial

OpenClaw docs → docs.openclaw.ai
OpenClaw GitHub → github.com/openclaw/openclaw

ClawHub → clawhub.ai

OpenRouter docs → openrouter.ai/docs

Ollama docs → github.com/ollama/ollama

Comunidades

Discord oficial de OpenClaw (enlace en docs.openclaw.ai)

Reddit: r/OpenClaw

Twitter/X: @openclaw, @AnthropicAI, @OpenAIDevs

Herramientas auxiliares imprescindibles

nvm (github.com/nvm-sh/nvm) — Gestión de versiones de Node.js

Traefik (traefik.io) — Reverse proxy con SSL automático (Let's Encrypt)

UFW — Firewall simple de Ubuntu

Docker (docker.com) — Aislamiento de servicios

Cloudflare Tunnels — Acceso remoto sin abrir puertos

Portainer (portainer.io) — UI gráfica para Docker (opcional)

VirusTotal (virustotal.com) — Análisis de archivos y URLs sospechosas

Newsletters y blogs útiles

Latent Space — IA para developers

The Rundown AI — Resumen diario de novedades en IA

Simon Willison's Blog — IA práctica y tooling

Sitio de LAT3DEV — pendiente de publicación

E — Siete trampas frecuentes (y cómo evitarlas)

1. Exponer el puerto 18789 a internet sin auth

Tu Gateway escucha en 0.0.0.0 y cualquiera con tu IP puede intentar mandarle mensajes.

Solución: En openclaw.json, configura el Gateway para escuchar solo en loopback según la sintaxis de tu versión. Combínalo con Traefik (Ruta A) o Cloudflare Tunnel (Ruta B). Verifica con ss -tlnp | grep 18789: debe mostrar 127.0.0.1.

2. API keys en el repositorio Git

Has commiteado openclaw.json con tu API key y ya está en GitHub para siempre.

Solución: usa variables de entorno, SecretRefs o el mecanismo de credenciales/auth profiles documentado por OpenClaw. Para Docker, usa .env y añade .env a .gitignore. Si ya cometiste el error, rota la API key inmediatamente en el panel del proveedor.

3. Skill sin auditar = riesgo desconocido

Instalas la Skill #342 de ClawHub porque «tiene buenas reviews». Las reviews pueden ser de bots.

Solución: Lee SKILL.md, revisa la ficha y auditorías de ClawHub, ejecuta clawhub inspect <slug> si tu versión de CLI lo soporta (comando sujeto a evolución; consulta clawhub --help), e instala primero en un agente de prueba. Aunque existan escaneos, no confíes ciegamente.

4. Modelo barato para tarea compleja

Usas Llama 3.1 8B para análisis financiero y te devuelve números inventados.

Solución: Modelo adecuado para la tarea. No ahorres en calidad cuando los datos importan. Para análisis con números, usa Claude Sonnet 4.6 o superior. Mistral Large 3 es un buen punto medio.

5. No hacer backup del workspace

VPS petado, sin backup, tres meses de configuración perdidos.

Solución: Cron diario con rsync a otro servidor o subida automática a Drive/S3. Como mínimo: ~/.openclaw/workspace/ y ~/.openclaw/openclaw.json.

6. Correr OpenClaw como root

OpenClaw corre como root dentro del contenedor. Si una Skill se vuelve loca, tiene acceso total.

Solución: Usuario no-root en Docker (USER 1000:1000 en el Dockerfile o user: en compose). --cap-drop=ALL. Filesystem read-only donde sea posible.

7. Ignorar los logs hasta que algo explota

Ejecutas openclaw doctor. 47 warnings. Los ignoras. Dos semanas después, tu agente está comprometido.

Solución: Revisa logs semanalmente. Si programas openclaw doctor con cron, usa la ruta absoluta de openclaw y un log propio. Si aparece algo en rojo, investígalo en el momento.

F — Misión del apéndice (30 minutos)

Regístrate en OpenRouter y obtén una API key (5 min)

Instala Ollama y descarga qwen3:8b (10 min: ollama pull qwen3:8b)

Busca 3 Skills en ClawHub que te interesen y revisa su ficha, SKILL.md, Files y Audits sin instalarlas todavía (10 min)

Configura un modelo principal y al menos un modelo de reserva en openclaw.json (5 min)

terminal/bash — comando copiable
openclaw gateway restart
openclaw doctor

Un arsenal no te hace más fuerte. Te hace más peligroso. Usa estas herramientas con cabeza, no con prisa.

LAT3DEV

La pieza que falta

Ya tienes los cimientos (Parte I). Los cerebros (Parte II). Tu ejército (Parte III). Y tu motor de facturación (Parte IV).

Pero hay una diferencia brutal entre montar un equipo y hacer que ese equipo trabaje coordinado sin que uno de tus agentes se cargue el servidor un domingo a las 3 AM porque alucinó con un comando de borrado.

Este apéndice nació en abril de 2026, después de que se publicara en GitHub una reimplementación en Rust inspirada en la arquitectura interna de un coding agent de referencia. Lo que sigue es la historia de cómo tomamos esos patrones de diseño —los mismos principios que usan los equipos serios para mantener docenas de agentes cooperando sin supervisión humana constante— y los adaptamos a OpenClaw sin escribir ni una línea de código nuevo.

Solo arquitectura. Patrones. Y un poco de paranoia con razón.

💡 Nota sobre el enfoque: Este apéndice describe patrones de diseño, no un fork ni una librería. Lo que vas a montar son archivos markdown y JSON que tu orquestador y tus agentes usan como convenciones operativas. Es portable, auditable y reversible. No sustituye controles reales como permisos, allow/deny de herramientas, sandboxing, autenticación del Gateway o auditorías soportadas por OpenClaw. Si algo sale mal, apartas la carpeta .claw/ y vuelves al punto de partida.

D — DEFINICIÓN: los 8 patrones que cambian las reglas

Cuando abres el código de un coding agent maduro, lo primero que llama la atención no son las herramientas ni el sistema de plugins. Es la capa de control. Estos sistemas no confían en sus propios agentes. Nunca. Cada llamada a una herramienta pasa por varios filtros antes de ejecutarse, y si algo falla, el sistema intenta autocorregirse antes de molestar al humano con una alerta.

Son 8 patrones. Cada uno protege una capa distinta. Juntos forman un sistema de defensa en profundidad que convierte tu bot doméstico en infraestructura multi-agente.

Un agente sin estos patrones es como un restaurante con un solo cocinero: puede funcionar hasta que llega la hora punta. Un agente con ellos tiene brigada, turnos y un jefe de cocina que dice «esto no sale, no está bien hecho».

Estructura de archivos resultante

~/.openclaw/workspace/.claw/

├── agent-profiles/

│ ├── explorer.json ← Perfil solo lectura

│ ├── planner.json ← Perfil lectura + escritura

│ ├── executor.json ← Perfil acceso total (requiere aprobación)

│ ├── mapping.json ← Qué agente → qué perfil

│ └── task-packet.md ← Contrato de delegación

├── pre-tool-hook-bouncer.md ← El portero de riesgo

├── hooks.md ← Hooks para herramientas externas

├── recovery-recipes.md ← 7 recetas de autocorrección

├── worker-state-observable.md ← Tracking de estado

├── policy-engine.md ← 10 políticas declarativas

├── summary-compression.md ← Compresión de contexto

├── active-agents.json ← Agentes activos ahora mismo

├── bouncer-log.jsonl ← Log: qué se permitió, qué se negó

├── policy-engine-log.jsonl ← Log: evaluación de políticas

├── recovery-log.jsonl ← Log: recuperaciones intentadas

├── worker-state-log.jsonl ← Log: cambios de estado

└── summary-compression-log.jsonl ← Log: compactaciones de contexto

Son 18 archivos. Alrededor de 35 KB en total. Y cero líneas de código nuevo: todo son documentos markdown y JSON que el orquestador interpreta como reglas de comportamiento.

E — ELIMINACIÓN: por qué un agente sin filtros es una bomba

Imagina que delegas al sub-agente «analista-experto» una comparativa de ofertas de empleo. Sin estos patrones, lo que ocurre es lo siguiente:

Sin Perfiles (Patrón 1): ese analista tiene exactamente las mismas herramientas que el tech-lead: ejecución de comandos, escritura, edición. El analista no necesita ejecutar comandos del sistema. Pero si el modelo alucina, puede intentarlo. No va a hacerlo el 99 % de las veces. Pero el punto es que no debería poder hacerlo nunca.

Principio de mínimo privilegio. No porque el agente sea malicioso, sino porque el modelo no es infalible. Y un modelo alucinando con permisos de ejecución es exactamente lo que separa un sistema fiable de un susto de viernes noche.

Sin Bouncer (Patrón 2): no hay nadie clasificando el riesgo de cada delegación. Una tarea de bajo riesgo y una de alto riesgo pasan exactamente igual. Sin filtro. Sin pregunta. Sin pausa para revisar.

Sin Recovery (Patrón 4): cuando un sub-agente falla, la respuesta por defecto es «escalo al humano». Eso no es autonomía. Es delegación sin red de seguridad. Y el resultado es que acabas gestionando 15 fallos en vez de cerrar 15 tareas.

Sin Policy Engine (Patrón 6): las reglas de seguridad están dispersas entre conversaciones, archivos markdown y tu memoria. No hay un sitio único donde auditar qué está permitido y qué no.

La matemática del paralelismo

Un agente con patrones rinde 3 veces más en tareas, falla 3 veces menos y te cobra 10 veces menos tiempo de gestión. Es como tener un equipo de tres trabajando en paralelo que solo te llama cuando de verdad hace falta.

A — AUTOMATIZACIÓN: 8 pasos, una mañana

Aquí van los pasos concretos para implementar esto en tu propio OpenClaw. Tardarás entre una y dos horas. Sin downtime. Sin reinicios de contenedores.

Paso 1: Backup (5 minutos)

Antes de tocar nada, copia tus archivos de configuración:

terminal/bash — comando copiable
mkdir -p ~/.openclaw/workspace/backup-pre-claw
cp ~/.openclaw/workspace/HEARTBEAT.md ~/.openclaw/workspace/backup-pre-claw/
cp ~/.openclaw/workspace/SOUL.md ~/.openclaw/workspace/backup-pre-claw/
cp ~/.openclaw/workspace/AGENTS.md ~/.openclaw/workspace/backup-pre-claw/
cp ~/.openclaw/workspace/IDENTITY.md ~/.openclaw/workspace/backup-pre-claw/ 2>/dev/null

Si algo falla, tienes a dónde volver.

Paso 2: Crear perfiles de agentes (15 minutos)

terminal/bash — comando copiable
mkdir -p ~/.openclaw/workspace/.claw/agent-profiles
mkdir -p ~/.openclaw/workspace/.claw/agent-state

Cada perfil es un JSON con las herramientas permitidas y el tiempo máximo de ejecución. La idea: tres niveles de privilegio.

explorer.json → solo lectura + búsqueda (investigador-web, lector)

planner.json → lectura + escritura + análisis (analista, redactor)

executor.json → acceso operativo completo (tech-lead, deploy-bot) — requiere aprobación explícita

Un archivo mapping.json dice: «el investigador-web es explorer, el tech-lead es executor».

Paso 3: Bouncer (10 minutos)

Crea pre-tool-hook-bouncer.md con un árbol de decisión. Cada vez que el orquestador vaya a delegar:

Clasifica el riesgo de la tarea: LOW, MEDIUM, HIGH

Mira el perfil del sub-agente que va a recibirla

Decide: ALLOW (adelante), DENY (no procede) o PENDING (requiere aprobación humana)

Paso 4: Hooks (15 minutos)

Crea hooks.md con cuatro hooks principales:

H-EMAIL para envío de correo (siempre PENDING en cuentas reales)

H-WEB para búsquedas y peticiones HTTP externas

H-EXEC para comandos del sistema (siempre HIGH risk)

H-IDENTITY para cambios de personalidad operativa en IDENTITY.md o comandos set-identity

Cada hook tiene pre-check (antes de ejecutar) y post-check (después). El post incluye sanitización: regex que detectan Bearer tokens, API keys y passwords, y los reemplazan con [REDACTED] antes de escribir en logs.

Paso 5: Recovery Recipes (15 minutos)

Crea recovery-recipes.md con 7 escenarios:

R1 — Timeout: la herramienta no responde en el tiempo esperado

R2 — Permiso denegado: el sub-agente no tiene la herramienta en su perfil

R3 — Policy block: una política del Patrón 6 bloqueó la acción

R4 — Output vacío: el sub-agente devolvió nada útil

R5 — Memoria corrupta: archivos del workspace inconsistentes

R6 — Bouncer mal clasifica: la clasificación de riesgo fue incorrecta

R7 — Infraestructura degradada: el proveedor o el VPS responden mal

Regla de oro: un intento de autocorrección. Uno. Luego escala al humano.

Paso 6: Worker State Observable (10 minutos)

Crea worker-state-observable.md y active-agents.json. Cada sub-agente delegado crea un archivo de estado en .claw/agent-state/<agent-id>.json. Si un agente está vivo, su last_ping se actualiza. Si pasan más de X minutos sin ping → stale → se dispara R7.

Paso 7: Policy Engine + Summary Compression (20 minutos)

Crea policy-engine.md con 10 políticas declarativas. Ejemplos típicos:

P1: «Nunca enviar email sin draft + revisión»
P2: «Nunca ejecutar rm -rf sin confirmación»
P3: «Nunca tocar archivos en /etc/ o /var/»
P4: «Cualquier acción que cueste más de 0,50 € en tokens requiere aprobación»

Crea summary-compression.md con el algoritmo de 3 fases:

Normaliza el contexto (quita ruido, formatos extraños)

Prioriza lo relevante (últimas N tareas, decisiones clave)

Trunca al presupuesto

Presupuesto recomendado: 4.000 caracteres para modelos con ventana de 128K, 6.000 caracteres para modelos de 200K.

Paso 8: Integrar en HEARTBEAT.md (20 minutos)

Añade al HEARTBEAT.md del orquestador las referencias a los 8 patrones. Si tu workspace usa IDENTITY.md como fuente principal de personalidad o el comando set-identity, registra ahí solo la identidad estable; deja las reglas de control en HEARTBEAT.md para no mezclar voz con permisos.

## Antes de cada delegación

1. Lee `.claw/agent-profiles/mapping.json` y confirma el perfil del sub-agente.

2. Aplica `.claw/pre-tool-hook-bouncer.md` para clasificar el riesgo.

3. Verifica políticas en `.claw/policy-engine.md`.

4. Si ALLOW → spawn. Si PENDING → pregunta al humano. Si DENY → registra y aborta.

5. Crea entrada en `.claw/agent-state/<agent-id>.json`.

## En cada respuesta del sub-agente

1. Aplica hooks de `.claw/hooks.md` (sanitización de output).

2. Si la respuesta supera el presupuesto → ejecuta `summary-compression.md`.

3. Actualiza `agent-state` con `last_ping`.

## Si algo falla

1. Aplica `.claw/recovery-recipes.md` (recipe correspondiente).

2. Un intento. Si vuelve a fallar → escala al humano.

El orquestador evalúa antes de cada delegación, no después. No al revés.

L — LIBERACIÓN: el sistema completo en marcha

Cómo trabajan juntos los 8 patrones

Delegación entrante

│

▼

┌──[1] Bouncer evalúa riesgo + perfil match

│

▼

┌──[2] Policy Engine evalúa P1-P10

│

▼

[3] Si ALLOW → spawn sub-agente con perfil de tools

│

│ (ejecución del sub-agente)

│

▼

┌──[4] Hooks interceptan tools externas (pre-check)

│

▼

┌──[5] Post-ejecución: sanitización del output

│

▼

┌──[6] Si fallo → Recovery Recipe (1 intento solo)

│

▼

┌──[7] Si éxito pero output largo → Summary Compression

│

▼

[8] Estado persiste en .claw/agent-state/ → observable

Cada capa es independiente. Puedes añadir, quitar o modificar una sin afectar las demás. Eso es diseño desacoplado. Y es lo que separa un sistema que escala de un sistema que se rompe en cuanto le tocas algo.

Lo que ganas con los 8 patrones funcionando

Tu orquestador con patrones no es más inteligente que el de tu vecino. Es más seguro. Y un agente que no se carga la infraestructura un domingo a las 3 AM es exactamente el tipo de compañero que quieres en un equipo que no cobra nómina, no pide vacaciones y acepta que le cambies el modelo.

Cinco trampas que te van a costar caras

1. No hacer backup del HEARTBEAT original

Vas a sobrescribir tu archivo de orquestación. Si no guardas el anterior, cuando algo vaya mal no sabrás a qué versión volver. Los 5 minutos del Paso 1 te ahorran 2 horas de reconstrucción.

2. Confundir Bouncer con Policy Engine

El Bouncer evalúa delegaciones (¿este perfil puede recibir esta tarea?). El Policy Engine evalúa todo lo demás (¿esta acción global cumple las políticas?). Son capas complementarias, no alternativas. El Bouncer dice «este perfil puede hacer esto». El Policy Engine dice «estas condiciones globales se cumplen». Necesitas los dos.

3. Recovery infinito

La tentación es poner max_attempts = 5 y dejar que el sistema reintente hasta que funcione. No lo hagas. Un bucle de recovery sin freno es más peligroso que el fallo original (puede vaciar tu crédito de OpenRouter en minutos, o saturar el VPS). Regla de oro: 1 intento. Si falla → escalar al humano. Punto.

4. Escribir políticas demasiado restrictivas

Si pones todas las políticas en DENY por defecto, tus agentes no hacen nada. Es como cerrar la puerta de casa con 8 cerraduras y perder las llaves. La seguridad es un balance, no un muro. Empieza con políticas razonables y ajusta con datos reales de los logs.

5. No leer los logs

Los archivos .jsonl son tu cuadro de mando. Si no los miras, es como tener un panel de control sin instrumentos. Revisa bouncer-log.jsonl y recovery-log.jsonl al menos una vez por semana. Te van a decir qué políticas son útiles y cuáles son ruido.

Misión del apéndice (30 minutos)

Backup (2 min):

terminal/bash — comando copiable
mkdir -p ~/.openclaw/workspace/backup-pre-claw
cp ~/.openclaw/workspace/*.md ~/.openclaw/workspace/backup-pre-claw/

Crear estructura .claw/ con los 3 directorios y los 18 archivos (15 min, copia los esqueletos de este apéndice)

Actualizar HEARTBEAT.md añadiendo las secciones de pre-delegación y post-ejecución (8 min)

Reiniciar el Gateway y prueba de fuego (5 min):

terminal/bash — comando copiable
openclaw gateway restart
openclaw doctor

Delega al investigador-web una búsqueda. Debería funcionar con perfil explorer. Si el Bouncer funciona, ese investigador no ve herramientas de ejecución.

Resumen del apéndice

Has llegado al final del manual.

Tienes los cimientos, el cerebro, el ejército, el motor de facturación y ahora la capa de control industrial. Tu Imperio de Uno no es una metáfora: es una arquitectura multi-agente concreta sobre la que puedes apilar todo lo que venga después.

Lo que hagas con ello ya no depende de este libro.

LAT3DEV

El dilema del Emperador

Tienes 6 sub-agentes. Cada uno hace una tarea distinta. ¿Pones Claude Opus en todos? Te gastas 300 € al mes y la mayoría del coste va a tareas que un modelo de 0,15 €/M también haría.

¿Pones el modelo más barato en todos? Tu agente principal alucina en decisiones críticas, tu generador de contenido escribe basura, y tu cliente cancela en la segunda semana.

La respuesta no es «un solo modelo para todo». Es stack de modelos por función: cada agente con el cerebro adecuado para su tarea, con fallback automático cuando algo falla. Y casi todos pueden ser gratuitos o costar céntimos.

Este apéndice es el mapa actualizado del arsenal disponible en 2026: qué modelos son gratis, cuáles cuestan céntimos por millón de tokens, cuáles van en local y cuáles en la nube. Y cómo combinarlos para que tu Imperio de Uno funcione sin que tu factura mensual se acerque al sueldo de un empleado.

⚠️ Disclaimer obligatorio: El panorama de modelos de IA cambia cada semana. Modelos nuevos aparecen, otros suben de precio, los free se convierten en de pago. Toda la información de este apéndice está verificada en mayo de 2026, pero antes de configurar nada en producción, consulta openrouter.ai/models y ollama.com/library para confirmar precios, IDs exactos y disponibilidad. Lo que aquí lees es el mapa; el territorio cambia mientras lo lees.

D — DEFINICIÓN: las tres capas del arsenal moderno

En 2026, el cerebro de tu agente se compone de tres capas posibles, no de una sola elección. Saber cuándo usar cada una es la diferencia entre pagar 5 € al mes y pagar 200 €.

Capa 1 — Modelos free vía API (OpenRouter)

OpenRouter mantiene una rotación de modelos completamente gratuitos. No es marketing: son modelos reales, frontier-adjacent, con un coste por token de cero. Subsidiados por OpenRouter, los providers, o ambos.

Limitaciones reales:

Rate limit: aproximadamente 20 peticiones por minuto, 200 por día por modelo

Pueden registrar tus prompts o respuestas según las condiciones del proveedor

Pueden desaparecer del free tier sin previo aviso

Latencia y disponibilidad menos garantizadas que el tier de pago

Cuándo usar:

Prototipado, experimentación, aprendizaje

Sub-agentes con uso esporádico (menos de 200 peticiones diarias)

Tareas no críticas que puedan reintentarse

Como fallback para reducir coste del modelo principal

Capa 2 — Modelos baratos vía API (OpenRouter, pay-per-use)

Por debajo de 0,50 $/M tokens de input, hay un universo de modelos que en 2025 eran de pago premium y en 2026 son commodity. Esta capa es la columna vertebral de cualquier agente de producción serio con presupuesto ajustado.

Cuándo usar:

Agente principal en producción

Sub-agentes con uso continuo

Tareas que requieren disponibilidad alta y latencia consistente

Cuando los rate limits del free tier ya te bloquean

Capa 3 — Modelos locales (Ollama)

Coste por token: 0 €. Coste real: tu hardware y tu electricidad. Privacidad total. Sin rate limits. Sin dependencia de internet.

Cuándo usar:

Cuando la privacidad es no negociable (datos sensibles)

Cuando quieres independencia total de proveedores

Cuando ya tienes hardware potente (16 GB+ de RAM)

Para tareas de alto volumen donde el coste de API se acumula

💡 Regla mental: No tienes que elegir una sola capa. Cualquier agente serio en 2026 combina las tres: modelo barato como principal, free como fallback, local para datos sensibles. El que mejor diseñe ese stack gana.

E — ELIMINACIÓN: por qué «un modelo para todo» es perder dinero

El error del modelo único

La mayoría de la gente que monta su primer agente comete el mismo error: pone Claude Sonnet o GPT-5 en todos los sub-agentes y se sorprende cuando la factura llega.

Veamos la matemática real. Supongamos 6 sub-agentes con uso medio:

Diferencia: 94 % de ahorro sin perder calidad en lo que importa. El truco no es ahorrar siempre, es gastar bien donde de verdad mueve la aguja.

Las tres trampas frecuentes

Trampa 1 — Usar el modelo más caro «por si acaso». El modelo más caro alucina exactamente igual que el barato en un 90 % de las tareas. La diferencia se nota solo en tareas de razonamiento complejo, análisis multi-paso o código intrincado. El resto del tiempo, estás pagando 100 € por un Mercedes que usas para ir al estanco.

Trampa 2 — Usar el modelo más barato sin fallback. Free tier se cae a las 11 de la mañana. Tu agente queda mudo. Tus clientes ven que no responde. Pierdes credibilidad. Solución: cadena de fallbacks (primary → fallback gratis → fallback barato).

Trampa 3 — Ignorar los modelos locales. Pones DeepSeek en la nube para resumir documentos confidenciales. Esos resúmenes se procesan en servidores de terceros que pueden almacenarlos. Para datos sensibles, Ollama local no es opcional: es obligatorio.

A — AUTOMATIZACIÓN: el catálogo verificado (mayo 2026)

Esta es la parte que cambia más rápido. Lee el disclaimer al inicio y verifica antes de configurar.

Catálogo 1 — Modelos FREE en OpenRouter

A mayo de 2026, OpenRouter ofrece 29 modelos completamente gratuitos. La rotación es constante: cada mes entran modelos nuevos y algunos salen. Aquí los más útiles para un Emperador de IA:

💡 A mayo de 2026, OpenRouter ofrece 29 modelos gratuitos. La tabla anterior recoge los más relevantes. Entre las incorporaciones más destacadas: NVIDIA Nemotron 3 Super 120B (1M context, reasoning frontier), GPT-OSS 120B (razonamiento frontier abierto de OpenAI, 131K), Google Gemma 4 31B (262K, multimodal) y MiniMax M2.5 (205K, multimodal). Para la lista completa actualizada, consulta openrouter.ai/models filtrando por «Free».

💡 El router gratuito openrouter/free elige automáticamente un modelo gratis adecuado para tu petición (soporta tool calling, vision, etc.). Útil cuando no quieres comprometerte a un modelo específico.

>

⚠️ La lista anterior es una selección de los 29 modelos gratuitos disponibles. La rotación es constante: modelos entran y salen del tier gratuito cada mes. Siempre verifica en openrouter.ai/models filtrando por «Free» antes de configurar un agente en producción.

Rate limits típicos del tier gratuito: 20 peticiones por minuto, 200 por día por modelo. Si los superas, tienes dos opciones: rota entre varios modelos free (los límites son por modelo, no globales) o pasa a la capa 2.

⚠️ Sobre privacidad en modelos free: Los providers que ofrecen un modelo :free suelen registrar prompts y completions para mejorar el modelo. Si manejas datos sensibles, no uses free tier. Usa modelos de pago con política de no-retención, o Ollama local.

Catálogo 2 — Modelos BARATOS de pago en OpenRouter

Precios en USD por millón de tokens (input/output), verificados en mayo de 2026.

💡 El descubrimiento del año: Xiaomi MiMo-V2-Flash entrega rendimiento comparable a Claude Sonnet 4.5 en SWE-Bench por aproximadamente el 3,5 % del precio. Si tu agente principal hace mucho tool calling y código ligero, esta es la opción que mejor combina calidad y precio en 2026. Cuando lo uses con OpenClaw, desactiva el modo de razonamiento si tu versión lo expone en la configuración; suele mejorar la velocidad en tareas mecánicas.

Catálogo 3 — Modelos LOCALES en Ollama

Modelos recomendados según el RAM disponible. Estos comandos los puedes ejecutar tal cual.

Hardware modesto (8 GB RAM)

terminal/bash — comando copiable

ollama pull qwen3:8b # All-rounder, multilingüe, buen tool calling

ollama pull gemma3:4b # Más rápido, suficiente para clasificación

ollama pull phi3:3.8b # El más rápido, tareas simples

Hardware medio (16 GB RAM) — el sweet spot

terminal/bash — comando copiable

ollama pull qwen3.6 # Recomendado por defecto para agente principal local (36B MoE, 262K context)

ollama pull qwen3:8b # Si qwen3.6 no está disponible, fallback sólido

ollama pull gpt-oss:20b # Razonamiento agentic, OpenAI open-weight

ollama pull deepseek-r1:8b # Chain-of-thought explícito

ollama pull mistral-small:3 # Multilingüe, 24B, buen español

ollama pull gemma3:12b # Reasoning sólido, eficiente

Hardware potente (24-32 GB RAM o más)

terminal/bash — comando copiable

ollama pull qwen3.6:35b # Variante 35B del 36B MoE, 262K context

ollama pull qwen3-coder:30b # Coding especializado, 256K context

ollama pull llama4:scout # 17B MoE, all-rounder Meta

Hardware bestia (48+ GB unified memory, dual GPU)

terminal/bash — comando copiable

ollama pull llama3.3:70b # All-rounder premium

ollama pull qwen3-coder:480b # SOTA local en código

ollama pull gpt-oss:120b # Razonamiento frontier abierto

⚠️ Sobre tool calling en local: No todos los modelos locales manejan bien las llamadas a herramientas que OpenClaw necesita. Los Qwen3.6 son los más fiables en 2026 para esto. Si tus tool calls fallan, desactiva el razonamiento explícito si tu versión de OpenClaw u Ollama expone esa opción, y verifica que tienes Ollama actualizado.

Configurar Ollama Cloud o Ollama remoto

Si no quieres correr Ollama en tu máquina, hay dos alternativas:

Opción A — Ollama en tu VPS (Ruta A). Instalas Ollama en tu VPS y OpenClaw lo consume vía HTTP. Útil si tu VPS tiene 16 GB+ de RAM. El comando:

terminal/bash — comando copiable
# En el VPS
curl -fsSL https://ollama.com/install.sh | sh

ollama pull qwen3:8b

# Por defecto escucha en localhost:11434

Opción B — Servicios cloud con API compatible Ollama. Hay providers como Together AI, Groq, Cerebras o Fireworks que ofrecen los mismos modelos open-source con API OpenAI-compatible. Algunos tienen tier gratuito generoso (Groq da 30 RPM en Llama 3.3 70B sin tarjeta de crédito, Cerebras 1 M de tokens diarios). Configuras OpenClaw como si fuera Ollama, pero apuntando a su endpoint.

Catálogo 4 — APIs directas con tier gratuito

💡 Estos proveedores ofrecen APIs directas con capas gratuitas generosas. A diferencia de OpenRouter —que unifica el acceso a cientos de modelos— aquí te registras directamente con cada proveedor. La ventaja: más control, menos intermediarios, y en varios casos más generosidad en el tier gratuito.

Todos estos proveedores permiten empezar sin tarjeta de crédito (salvo xAI). La configuración en OpenClaw sigue el mismo patrón: das de alta el proveedor y guardas la credencial en el mecanismo seguro de tu versión (openclaw configure, SecretRef, variable de entorno segura o perfil de autenticación). No pegues API keys en texto plano dentro de openclaw.json. Consulta la documentación actualizada de cada proveedor antes de registrarte: los tiers gratuitos y precios cambian con frecuencia.

Cómo elegir el modelo de cada sub-agente

El árbol de decisión

¿La tarea maneja datos sensibles o confidenciales del cliente?

- Sí → Ollama local. No negociable.

- No → Continúa.

¿El volumen mensual estimado supera 200 peticiones/día?

- No → Empieza con free tier (Llama 3.3 70B o el router openrouter/free).

- Sí → Continúa.

¿La tarea requiere razonamiento complejo (análisis multi-paso, decisiones con consecuencias, código no trivial)?

- No → Capa barata: MiMo-V2-Flash, DeepSeek V4 Flash, Mistral Small 4.

- Sí → Continúa.

¿Es una tarea crítica donde un error te cuesta dinero o reputación?

- Sí → Modelo premium: Claude Sonnet 4.6, DeepSeek V3.2 Speciale, GPT-5.

- No → Capa barata-media: DeepSeek V3.2, Gemini 3 Flash Preview.

Plantilla de configuración por tipo de sub-agente

Ejemplo orientativo en openclaw.json

Así puede quedar el bloque de modelos para un agente principal con fallback en tres capas. No lo copies a ciegas: el esquema exacto de openclaw.json puede variar entre versiones. Valídalo con openclaw doctor o ajusta modelos desde openclaw configure si tu instalación lo soporta.

{

"agents": {

"main": {

"model": {

"primary": "xiaomi/mimo-v2-flash",

"fallbacks": [

"deepseek/deepseek-v3.2",

"meta-llama/llama-3.3-70b-instruct:free",

"ollama/qwen3.6"

]
}
},

"investigador-web": {

"model": {

"primary": "qwen/qwen3-plus:free",

"fallbacks": [

"google/gemini-2.5-flash-lite"

]
}
},

"asesor-financiero": {

"model": {

"primary": "anthropic/claude-sonnet-4.6",

"fallbacks": [

"deepseek/deepseek-v3.2-speciale"

]
}
}
}
}

Después de editar, reinicia el Gateway:

terminal/bash — comando copiable
openclaw gateway restart
openclaw doctor

La estrategia free-first para empezar con 0 €

Si quieres montar tu primer agente sin gastar nada (literal, ni un céntimo), aquí está la receta exacta:

Setup zero-cost completo

Cuenta en OpenRouter (gratis, sin tarjeta) → openrouter.ai

Cuenta en Groq (gratis, sin tarjeta) → groq.com

Cuenta en Cerebras (gratis, sin tarjeta) → cloud.cerebras.ai

Ollama instalado en local si tienes 16 GB+ de RAM

Stack de fallback en 4 niveles

Petición del agente

│

▼

[1] OpenRouter: qwen/qwen3-plus:free

│ (si rate limit)

▼

[2] OpenRouter: meta-llama/llama-3.3-70b-instruct:free

│ (si rate limit)

▼

[3] Groq: llama-3.3-70b (30 RPM gratis, super rápido)

│ (si rate limit o caída)

▼

[4] Ollama local: qwen3.6 (siempre disponible)

Coste real al mes con este stack: 0,00 €. Límite práctico: entre 5.000 y 15.000 peticiones diarias bien distribuidas si el dispatcher hace su trabajo.

⚠️ Sobre los modelos free en producción seria: Funcionan, pero no son fiables para clientes que pagan. Tu cliente no entiende de rate limits. Lo que sí entiende es que «el bot no responde». Para producción profesional, pasa al menos el modelo principal a capa de pago barata (DeepSeek V4 Flash a 0,14 $/M es suficiente para casi cualquier caso real) y deja los free como fallback.

Errores comunes al elegir modelos

1. Bloquearse en un solo proveedor

Atarse a Claude o GPT-5 «porque son los mejores» cuando el 80 % de las tareas las resuelve un modelo 10 veces más barato. Diversifica de día uno. OpenRouter te permite cambiar el modelo con una sola línea de configuración: úsalo.

2. Confiar ciegamente en benchmarks

Un modelo top en LiveCodeBench puede ser malo escribiendo emails en español. Un modelo regular en MMLU puede manejar tu nicho perfectamente. Prueba con tu caso real, no con el ranking de moda.

3. No medir el coste real

Pones DeepSeek V3.2 «porque es barato» y luego descubres que tu sub-agente genera respuestas de 5.000 tokens cada vez. Output a 0,40 $/M × 5K × 30 días × 100 peticiones diarias = 60 $. Mide el coste por petición, no solo el precio por token.

4. Ignorar los modelos no-occidentales

Qwen, DeepSeek, GLM, MiMo, Kimi: son los modelos más interesantes de 2026 en ratio calidad/precio. Mucha gente los descarta por prejuicio geográfico y se pierde el mejor stack económico disponible.

5. Configurar fallbacks que apuntan al mismo proveedor

Si tu fallback de OpenRouter es otro modelo de OpenRouter, y OpenRouter se cae, tu agente se cae. Diversifica también los proveedores en la cadena de fallback (OpenRouter → Groq → Ollama local).

L — LIBERACIÓN: tu agente cuesta lo que tú decidas

Tres escenarios de coste real

Compara con el coste de un empleado júnior: 1.500-2.000 € al mes. O con el coste de una herramienta SaaS equivalente: 50-300 € al mes por usuario.

Tu agente puede hacer el trabajo de 5 personas y costar menos que una pizza familiar al mes. Esa es la matemática del Imperio de Uno bien construido.

El check de salud mensual

Una vez al mes, dedica 10 minutos a:

Revisar tu dashboard de OpenRouter y ver qué modelos consumieron más tokens

Identificar el sub-agente más caro y preguntarte si está justificado

Probar el siguiente modelo más barato en una tarea típica de ese sub-agente

Revisar la rotación de modelos free (los IDs cambian; modelos nuevos sustituyen a viejos)

Actualizar openclaw.json con los cambios y reiniciar:

terminal/bash — comando copiable
openclaw gateway restart
openclaw doctor

Esta revisión te ahorrará entre el 20 % y el 60 % de tu factura mensual sin perder calidad. Es la diferencia entre un imperio rentable y uno que sangra dinero.

Resumen del apéndice

⚠️ Recordatorio del disclaimer: este apéndice está verificado en mayo de 2026. Los modelos free cambian, los precios bajan (y a veces suben), aparecen modelos nuevos cada mes. Antes de configurar producción:

- Verifica precios en openrouter.ai/models

- Confirma disponibilidad en Ollama en ollama.com/library

- Lee los términos de privacidad de cada modelo que uses para datos no triviales

- Mantén la cadena de fallback diversificada entre al menos dos proveedores distintos

Tu Imperio no se mide en cuánto gastas. Se mide en cuánto consigues con lo que gastas. Un agente bien stackeado con 3 € al mes hace más que uno mal configurado con 300 €.

El arsenal está aquí. La estrategia también. Ahora te toca a ti probar, medir y ajustar.

LAT3DEV

Cada entrada sigue la misma estructura:

Síntoma: lo que ves en la pantalla.

Causa más probable: por qué pasa (en español, no en jerga técnica).

Comando copiable: lo que ejecutas para arreglarlo.

Si no funcionó: el siguiente paso lógico, sin vueltas.

💡 Antes de bucear en la tabla, ejecuta esto:

terminal/bash — comando copiable
openclaw doctor
openclaw gateway status

Es tu botón de «¿está todo bien?». Comprueba el Gateway, la configuración, los canales conocidos, los permisos del workspace y más. Si el diagnóstico sale limpio y el problema persiste, entonces sí, sigue leyendo.

1 — Node.js y npm (instalación)

Capítulos relacionados: Capítulo 3

Diagnóstico rápido

EACCES: permission denied

Causa más probable: Usaste sudo con npm

Comando copiable: Quita el sudo. nvm instala en tu usuario, sin permisos especiales.

Si no funcionó: npm config set prefix ~/.local y añade ~/.local/bin al PATH

node: command not found

Causa más probable: Node no está en el PATH

Comando copiable: source ~/.bashrc (Linux) o source ~/.zshrc (macOS), o abre una terminal nueva.

Si no funcionó: export NVM_DIR="$HOME/.nvm" && [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

nvm: command not found

Causa más probable: nvm no se cargó en la sesión

Comando copiable: Cierra la terminal y abre otra.

Si no funcionó: Vuelve a ejecutar el script de instalación de nvm desde github.com/nvm-sh/nvm

npm ERR! code ENOENT

Causa más probable: Carpeta equivocada

Comando copiable: Navega con cd al directorio correcto del proyecto.

Si no funcionó: pwd para confirmar dónde estás

--openssl-legacy-provider is not allowed

Causa más probable: NODE_OPTIONS incompatible o toolchain antigua frente a Node moderno

Comando copiable: unset NODE_OPTIONS && nvm install 24 && nvm use 24

Si no funcionó: Verifica con node --version que tienes Node 24 o, como mínimo verificado para OpenClaw 2026.5.19, 22.19+

npm ERR! code EACCES (instalando global)

Causa más probable: sudo rompió los permisos de npm

Comando copiable: Reinstala nvm sin sudo y vuelve a npm install -g openclaw@latest.

Si no funcionó: which npm para confirmar que usas el npm de nvm, no el del sistema

2 — SSH y Conexión al VPS

Capítulos relacionados: Capítulo 4, Capítulo 5

Diagnóstico rápido

Connection refused

Causa más probable: El VPS aún no está listo o el puerto SSH está cerrado

Comando copiable: Espera dos minutos tras crear el VPS y vuelve a intentar.

Si no funcionó: Revisa en el panel de tu proveedor que el puerto 22 está abierto

Connection timed out

Causa más probable: Un firewall bloquea el puerto 22

Comando copiable: Revisa las reglas de firewall en el panel de tu proveedor y asegura que el puerto 22 está abierto para tu IP.

Si no funcionó: Prueba desde otra red (móvil con datos, otra WiFi)

Permission denied

Causa más probable: Contraseña incorrecta o usuario equivocado

Comando copiable: Revisa que usas root@TU_IP y que la contraseña es la que te dio el proveedor.

Si no funcionó: Resetea la contraseña de root desde el panel del proveedor

node: command not found tras reconectar por SSH

Causa más probable: nvm no se cargó en .bashrc

Comando copiable: grep nvm ~/.bashrc para verificar. Si falta, añade el snippet oficial de NVM_DIR del README de nvm y abre una terminal nueva.

Si no funcionó: source ~/.bashrc y luego node --version

3 — Gateway de OpenClaw

Capítulos relacionados: Capítulo 5, Capítulo 6, Capítulo 8

Diagnóstico rápido

El Gateway no arranca

Causa más probable: Falta una API key o la configuración es inválida

Comando copiable: openclaw gateway status && openclaw doctor

Si no funcionó: en Linux con servicio de usuario, prueba journalctl --user -u openclaw-gateway -n 50 --no-pager; después revisa la configuración con openclaw configure

El puerto 18789 está ocupado

Causa más probable: Otro proceso (o una instancia anterior del Gateway) lo retiene

Comando copiable: openclaw gateway status && openclaw gateway restart

Si no funcionó: lsof -i :18789 para identificar el proceso; usa kill PID primero y kill -9 PID solo como último recurso, cuando entiendas qué proceso estás cerrando.

El Gateway escucha en 0.0.0.0 (expuesto a internet)

Causa más probable: La configuración bind no está en loopback

Comando copiable: openclaw gateway status y ss -tlnp | grep 18789. En una instalación nativa, corrige a loopback con la configuración documentada por tu versión y reinicia con openclaw gateway restart.

Si no funcionó: en Docker, bind=lan dentro del contenedor no equivale automáticamente a internet abierto. Revisa docker compose ps o docker ps --format "table {{.Names}}\t{{.Ports}}" para confirmar qué puertos salen al host.

Docker dice que falta gateway.mode

Causa más probable: El setup.sh generó configuración incompleta para el Gateway.

Comando copiable: openclaw config set gateway.mode local y openclaw config set gateway.bind lan; si falla la UI, revisa que gateway.controlUi.allowedOrigins permita http://localhost:18789 y http://127.0.0.1:18789. Después reinicia el stack o el Gateway.

Si no funcionó: verifica con openclaw config get gateway.mode, openclaw gateway status, curl -s http://127.0.0.1:18789/healthz y curl -s http://127.0.0.1:18789/readyz.

openclaw: command not found

Causa más probable: OpenClaw no está instalado o no está en el PATH

Comando copiable: which openclaw. Si no aparece: npm install -g openclaw@latest.

Si no funcionó: export PATH=$PATH:$(npm config get prefix)/bin y vuelve a probar

El modelo da errores al responder

Causa más probable: Provider mal configurado o sin crédito

Comando copiable: openclaw doctor. No pegues openclaw.json completo en chats: puede contener rutas, perfiles de autenticación o referencias sensibles.

Si no funcionó: revisa el perfil de autenticación, SecretRef o variable segura que use tu versión; si dudas, reconfigura con openclaw configure

4 — Ollama (modelos locales)

Capítulos relacionados: Capítulo 9

Diagnóstico rápido

Killed o el proceso muere solo

Causa más probable: Out of memory (OOM): el modelo no cabe en tu RAM

Comando copiable: Cambia a un modelo más pequeño (ej. qwen3.5:2B). O añade swap: sudo fallocate -l 8G /swapfile && sudo chmod 600 /swapfile && sudo mkswap /swapfile && sudo swapon /swapfile.

Si no funcionó: Nunca cargues un modelo mayor del 60 % de tu RAM total. Si tienes 8 GB, modelos de 4B como máximo

Menos de 5 tokens/s (muy lento)

Causa más probable: GPU no detectada o drivers ausentes

Comando copiable: ollama ps y nvidia-smi para diagnosticar. En Linux, instala drivers NVIDIA CUDA o AMD ROCm siguiendo la guía oficial de tu GPU/distro.

Si no funcionó: Apple Silicon se detecta automáticamente. Si no mejora, usa modelos más pequeños.

OpenClaw no conecta con Ollama

Causa más probable: Ollama está parado o la URL es incorrecta

Comando copiable: ollama list y curl http://127.0.0.1:11434/api/tags. Si no responde: ollama serve &.

Si no funcionó: Revisa models.providers en openclaw.json y los logs del Gateway; en Linux con systemd de usuario: journalctl --user -u openclaw-gateway -n 100 --no-pager | grep -i ollama

Respuestas incoherentes o en mal español

Causa más probable: Cuantización demasiado baja (Q2/Q3)

Comando copiable: Usa Q4_K_M como mínimo. Para español, prefiere Qwen3 o Qwen3.5. Descarga la versión por defecto: ollama pull qwen3:8b.

Si no funcionó: Prueba con ollama run qwen3.5:4b y evalúa la calidad antes de integrar

Ollama satura toda la RAM

Causa más probable: Demasiados modelos cargados a la vez

Comando copiable: Limita modelos concurrentes con variables de entorno de Ollama (OLLAMA_MAX_LOADED_MODELS=1, OLLAMA_NUM_PARALLEL=1). En systemd: sudo systemctl edit ollama, añade [Service] con Environment="OLLAMA_MAX_LOADED_MODELS=1", luego sudo systemctl daemon-reload && sudo systemctl restart ollama.

Si no funcionó: Verifica los modelos cargados con ollama ps

El modelo no aparece en ollama list

Causa más probable: No se ha descargado

Comando copiable: ollama pull qwen3:8b (o el modelo que necesites).

Si no funcionó: Comprueba conexión a internet y espacio en disco con df -h

5 — Modelos Cloud y OpenRouter

Capítulos relacionados: Capítulo 10, Apéndice E

Diagnóstico rápido

Errores 401, 402, 403 o 429 del proveedor

Causa más probable: 401 = credenciales inválidas; 402 = crédito insuficiente; 403 = permiso, guardrail o moderación; 429 = rate limit

Comando copiable: openclaw doctor para verificar credenciales; en OpenRouter, revisa GET https://openrouter.ai/api/v1/key desde un entorno seguro si necesitas crédito/rate limit.

Si no funcionó: Entra en OpenRouter > Settings > Keys y verifica estado, límites y crédito antes de rotar la key

El modelo responde con errores o inventa datos

Causa más probable: Modelo barato usado para tarea compleja

Comando copiable: Cambia a un modelo premium verificado en el Apéndice E para números/datos; para tareas simples, un Qwen local o un modelo barato verificado puede sobrar.

Si no funcionó: Configura fallbacks en openclaw.json: primario premium + secundario barato

La API gratuita se cae a media mañana

Causa más probable: Las free tiers tienen límites de uso diario

Comando copiable: Configura agents.defaults.model.primary y agents.defaults.model.fallbacks con modelos verificados ese día.

Si no funcionó: Nunca dependas de un solo provider gratuito para tareas de producción

6 — Telegram y Canales

Capítulos relacionados: Capítulo 13

Diagnóstico rápido

El bot no responde

Causa más probable: Gateway parado

Comando copiable: openclaw gateway restart.

Si no funcionó: openclaw gateway status para confirmar que está corriendo

El bot no responde (Gateway OK)

Causa más probable: Token de BotFather incorrecto

Comando copiable: Reconfigura Telegram con openclaw channels login si tu versión lo soporta, o usa el flujo documentado por openclaw channels --help. Guarda el token como SecretRef, variable segura o perfil de autenticación; no lo dejes en texto plano ni lo pegues en chats, capturas o logs compartidos.

Si no funcionó: openclaw channels status --channel telegram para confirmar que Telegram aparece cargado; si necesitas comandos de diagnóstico más finos, consulta openclaw channels --help porque los subcomandos cambian entre versiones

«Channel not configured»

Causa más probable: Canal no añadido o no cargado por el Gateway

Comando copiable: openclaw channels status.

Si no funcionó: vuelve a ejecutar el flujo de alta con openclaw channels login o con el comando que muestre openclaw channels --help en tu versión

Respuesta muy lenta

Causa más probable: Modelo pesado o VPS saturado

Comando copiable: Cambia el modelo a uno más rápido (ej. de Sonnet a Qwen3 8B para tareas simples). Revisa recursos del VPS con htop.

Si no funcionó: Si usas Ollama, considera migrar el bot principal a un modelo cloud

No empareja (modo pairing)

Causa más probable: El código de emparejamiento expiró

Comando copiable: Reinicia el Gateway con openclaw gateway restart y repite el flujo de emparejamiento.

Si no funcionó: revisa los logs del servicio (journalctl --user -u openclaw-gateway -n 100 --no-pager) y busca errores del canal

Responde en inglés en vez de español

Causa más probable: SOUL.md no tiene regla de idioma

Comando copiable: Añade al SOUL.md del agente: Responde siempre en español; usa comillas angulares para citas en prosa y tú/usted según el contexto.

Si no funcionó: Verifica también el system prompt del modelo en la configuración del proveedor

Filtra logs específicos del canal Telegram

Causa más probable: Necesitas aislar el problema

Comando copiable: openclaw channels status y openclaw agents list --bindings.

Si no funcionó: filtra los logs del Gateway con journalctl --user -u openclaw-gateway -n 100 --no-pager | grep -i telegram

7 — SOUL.md, IDENTITY.md y personalidad del agente

Capítulos relacionados: Capítulo 14

Diagnóstico rápido

El agente se diluye o suena genérico

Causa más probable: SOUL.md demasiado largo (>5.000 caracteres)

Comando copiable: Córtalo hasta que se lea completo en menos de 2 minutos. Cada frase debe ser una instrucción observable.

Si no funcionó: Pídele al agente que se presente: si no te convence en 30 segundos, el SOUL está diluido

El agente improvisa demasiado

Causa más probable: Adjetivos sin acción («sé creativo», «sé profesional»)

Comando copiable: Sustituye por acciones observables: «Usa frases de 2-3 líneas», «Cierra siempre con una pregunta», «Nunca uses jerga técnica sin explicarla».

Si no funcionó: Revisa las conversaciones de los últimos 3 días y anota las 3 peores respuestas para corregirlas

Contradicciones entre SOUL.md y AGENTS.md

Causa más probable: Mezclaste personalidad con procedimientos

Comando copiable: SOUL.md = cómo habla y decide; IDENTITY.md = cómo se presenta; AGENTS.md = cómo trabaja (reglas operativas, protocolos, routing). Sepáralos.

Si no funcionó: Revisa el Capítulo 11 para el desglose completo de los 8 archivos del workspace

El agente pierde el tono con el tiempo

Causa más probable: No actualizas SOUL.md y tu negocio cambia

Comando copiable: Revisa SOUL.md cada 2 semanas. Si añades un servicio nuevo, actualiza el SOUL.

Si no funcionó: Haz una revisión trimestral completa: ¿el agente sigue representándote?

8 — Workspace y Sub-agentes (Cuarentena)

Capítulos relacionados: Capítulo 17

Diagnóstico rápido

Datos de un sub-agente aparecen en el workspace de otro

Causa más probable: Comparten el mismo workspace en vez de estar aislados

Comando copiable: Cada sub-agente necesita su propio workspace configurado. En la CLI: openclaw agents add nombre --workspace ~/.openclaw/workspace-nombre.

Si no funcionó: Revisa con openclaw agents list --bindings que cada agente tiene su workspace único

openclaw.json visible para otros usuarios del sistema

Causa más probable: Permisos débiles (644 o peor)

Comando copiable: chmod 600 ~/.openclaw/openclaw.json. Nunca bajes de 600.

Si no funcionó: ls -la ~/.openclaw/openclaw.json para verificar que muestra -rw-------

Sub-agente eliminado pero su workspace sigue ocupando espacio

Causa más probable: No limpiaste al borrar

Comando copiable: Usa openclaw agents delete <nombre> si el agente sigue registrado y aceptas borrar ese registro. Si limpias a mano, primero mueve a cuarentena: mv ~/.openclaw/workspace-nombre ~/.openclaw/quarantine/workspace-nombre-$(date +%Y%m%d).

Si no funcionó: openclaw agents list --bindings y ls ~/.openclaw/ para revisar qué workspaces están activos de verdad

API key expuesta en logs del sub-agente

Causa más probable: Pasaste la key como texto en el mensaje de spawn

Comando copiable: Nunca pases credenciales en texto plano. Usa SecretRefs, variables de entorno seguras o el mecanismo de credenciales/auth profiles de OpenClaw.

Si no funcionó: Si ya ocurrió, rota la API key inmediatamente en el panel del proveedor

9 — Heartbeats y Comunicación

Capítulos relacionados: Capítulo 18

Diagnóstico rápido

Consumo de tokens disparado sin motivo aparente

Causa más probable: Heartbeats demasiado frecuentes

Comando copiable: Espacia los heartbeats: agente principal cada 24 h, sub-agentes cada 12 h o más. Cada heartbeat cuesta tokens.

Si no funcionó: Calcula: frecuencia_diaria x nº_agentes x tokens_promedio = tu gasto diario estimado

El heartbeat tarda 15 minutos en ejecutarse

Causa más probable: HEARTBEAT.md contiene tareas demasiado pesadas

Comando copiable: Divide las tareas en bloques que se resuelvan en menos de 2 minutos cada uno. Si una tarea necesita 10 minutos, está mal delegada.

Si no funcionó: Mueve tareas pesadas a AGENTS.md como procedimientos bajo demanda, no en el heartbeat

Fallos en loop a las 3 AM

Causa más probable: El agente insiste fuera de la ventana útil o depende de un modelo gratuito saturado

Comando copiable: Limita la ventana de ejecución si tu versión soporta activeHours; si no, mueve la acción a Scheduled Tasks/Cron y revisa logs.

Si no funcionó: Revisa los patrones de fallo en los logs semanalmente

Sub-agente desaparece sin dejar rastro

Causa más probable: Cancelas sesiones sin intentar redirigirlas o recuperar contexto

Comando copiable: Usa la UI de tu orquestador o la CLI de OpenClaw para gestionar sesiones. Comandos concretos de steer/kill: consulta openclaw agents --help y la documentación de tu versión; la CLI evoluciona rápido.

Si no funcionó: Configura 1 reintento automático. Si falla, escala al humano. No hagas bucles de reintentos sin freno

10 — Navegador y Scraping

Capítulos relacionados: Capítulo 20

Diagnóstico rápido

«No puedo abrir el navegador»

Causa más probable: Chromium no está instalado en el VPS

Comando copiable: Instala Chromium/Chrome según tu distro o configura browser.executablePath en OpenClaw.

Si no funcionó: Verifica la instalación con el comando de tu distro (chromium --version, google-chrome --version o equivalente)

La web se ve diferente a lo que esperabas

Causa más probable: El contenido dinámico (JavaScript) tarda en cargar

Comando copiable: Pídele al agente «espera a que la página cargue completamente antes de extraer datos».

Si no funcionó: Si el problema persiste, la web puede estar bloqueando navegadores headless

«CAPTCHA detectado» en el VPS

Causa más probable: La web detecta comportamiento de bot (demasiadas visitas/hora)

Comando copiable: Reduce frecuencia: máximo 100 visitas/hora a la misma web. Añade pausas aleatorias.

Si no funcionó: Para webs con CAPTCHAs frecuentes, tu agente te avisa y tú intervienes manualmente

No extrae los datos correctos

Causa más probable: La web cambió el diseño

Comando copiable: Pídele al agente una captura de pantalla para que veas lo que él ve.

Si no funcionó: Actualiza las instrucciones de extracción con los nuevos selectores

No entra en una web con login*

Causa más probable: La sesión expiró o requiere 2FA

Comando copiable: Inicia sesión manualmente una vez en el perfil persistente del navegador. El agente mantendrá la sesión.

Si no funcionó: Si pide 2FA cada vez, esa web no es automatizable; tu agente te avisará

11 — Voz (ElevenLabs)

Capítulos relacionados: Capítulo 22

Diagnóstico rápido

«No se genera audio»

Causa más probable: API key incorrecta o skill no instalada

Comando copiable: Ejecuta openclaw doctor y revisa la sección de skills. Reinstala si es necesario.

Si no funcionó: instala la integración de voz con openclaw skills install <slug> usando un slug verificado en ClawHub (busca elevenlabs, elevenlabs-voice, o similar; verifica autor y auditorías antes de instalar).

Voz robótica o poco natural

Causa más probable: Parámetro stability demasiado alto

Comando copiable: Baja stability a 0,4-0,5 en la configuración de la skill.

Si no funcionó: Prueba con eleven_multilingual_v2 para español

El audio tarda mucho en generarse

Causa más probable: Texto demasiado largo

Comando copiable: Divide el texto en fragmentos de 500 caracteres máximo.

Si no funcionó: Limita la generación de voz a briefings y alertas importantes

Se agotan los caracteres gratis demasiado rápido

Causa más probable: Estás usando voz para todo

Comando copiable: Sube de plan en ElevenLabs o limita a casos de alto valor: briefings diarios, alertas urgentes, mensajes de bienvenida.

Si no funcionó: No uses voz para tablas de datos ni información sensible.

Pronunciación rara en español

Causa más probable: Voz entrenada principalmente en inglés

Comando copiable: Usa modelo eleven_multilingual_v2 con una voz cuyo idioma principal sea español.

Si no funcionó: Prueba varias voces antes de decidir; la demo de ElevenLabs es gratuita

12 — Prospección y Emails

Capítulos relacionados: Capítulo 21

Diagnóstico rápido

El investigador trae leads irrelevantes

Causa más probable: ICP (Perfil de Cliente Ideal) poco específico

Comando copiable: Detalla más en USER.md: sector, tamaño de empresa, cargo del contacto, ubicación, señales de compra.

Si no funcionó: Pídele 10 leads de prueba y evalúa cuántos son relevantes. Si menos del 50 %, refina el ICP

Los emails suenan genéricos

Causa más probable: SOUL.md no captura tu tono de venta

Comando copiable: Añade al SOUL 3 ejemplos reales de emails que sí escribirías.

Si no funcionó: Prueba con un prompt más concreto: «Redáctalo como si se lo escribieras a un colega de confianza»

LinkedIn bloquea las búsquedas

Causa más probable: Scraping directo a LinkedIn es agresivo y detectable

Comando copiable: Usa web_search o Google dorking en vez de navegar LinkedIn directamente.

Si no funcionó: Si necesitas LinkedIn sí o sí, baja la frecuencia a 10-20 perfiles/día con pausas largas

Demasiados leads para revisar

Causa más probable: El umbral de filtro es demasiado bajo

Comando copiable: Sube el umbral del analista a 8+ sobre 10 en las instrucciones de AGENTS.md.

Si no funcionó: Automatiza: solo te llegan los que superan el umbral

*Emails enviados sin respuestas

Causa más probable: Mensaje no personalizado o CTA débil

Comando copiable: Revisa la estructura: gancho personalizado + problema concreto + solución específica + CTA clara.

Si no funcionó: Prueba A/B con 10 leads cada versión y mide respuesta en 48 h

13 — Micro-SaaS / Monetización

Capítulos relacionados: Capítulo 23, Capítulo 24

Diagnóstico rápido

Construiste algo que nadie quiere

Causa más probable: No validaste antes de construir

Comando copiable: Habla con 10 personas del nicho ANTES de escribir código. Si 5+ dicen «lo quiero», sigue.

Si no funcionó: Reformula: «Mi Micro-SaaS ayuda a [NICHO] a [RESOLVER PROBLEMA] por [PRECIO] €/mes.»

Tienes usuarios pero no pagas las facturas

Causa más probable: No cobraste desde el día 1

Comando copiable: El plan gratuito capta; el de pago da de comer. Lanza con ambos.

Si no funcionó: Con 5 usuarios, gestionar pagos manualmente son 2 min/día. Automatiza cuando duela de verdad.

Pasas 8 horas montando webhooks de Stripe para 5 clientes

Causa más probable: Estás automatizando antes de tener volumen

Comando copiable: Automatiza solo cuando la tarea manual consuma más de 30 min/día. Antes de eso, hazlo a mano.

Si no funcionó: Prioriza: 1) producto que funcione, 2) primeros clientes, 3) automatización de cobros

Te copian la idea en 2 semanas

Causa más probable: Tu SaaS es demasiado genérico

Comando copiable: Especializa: no hagas «monitor de precios». Haz «monitor de precios de componentes de PC para gamers españoles». Cuanto más nicho, menos competencia.

Si no funcionó: Añade una barrera de entrada: datos propios, integración exclusiva, comunidad

Te denuncian por no tener política de privacidad

Causa más probable: Ignoraste lo legal porque «total, son 10 usuarios»

Comando copiable: 30 minutos en TermsFeed o un generador similar cubren lo básico: política de privacidad, términos de servicio, aviso de cookies.

Si no funcionó: Consulta con un abogado si manejas datos sensibles o pagos

14 — Docker

Capítulos relacionados: Capítulo 5, Apéndice A

Diagnóstico rápido

Un contenedor no arranca

Causa más probable: Error de configuración o dependencia

Comando copiable: docker compose ps para el estado y docker compose logs --tail 50 para ver el error. En OpenClaw, comprueba además curl -s http://127.0.0.1:18789/healthz.

Si no funcionó: docker compose down && docker compose up -d para reinicio limpio

Disco lleno por Docker

Causa más probable: Imágenes, volúmenes y contenedores acumulados

Comando copiable: docker system df para ver qué ocupa. Si lo entiendes, no estás en un host de producción desconocido y los servicios críticos no están activos, docker system prune -f limpia recursos no usados; no borra volúmenes por defecto.

Si no funcionó: revisa docker volume ls y usa filtros por antigüedad. Evita --volumes salvo que hayas confirmado que esos volúmenes no contienen datos.

OpenClaw corre como root en el contenedor

Causa más probable: Configuración insegura de Docker

Comando copiable: Añade en docker-compose.yml: user: "1000:1000", cap_drop: ["ALL"] y sistema de archivos read-only donde sea posible.

Si no funcionó: Nunca expongas el socket de Docker al contenedor de OpenClaw

15 — Seguridad y Sistema

Capítulos relacionados: Capítulo 7, Apéndice C

Diagnóstico rápido

Puerto 18789 expuesto a internet sin autenticación

Causa más probable: El Gateway está en bind: "0.0.0.0" en vez de loopback

Comando copiable: ss -tlnp | grep 18789 y openclaw gateway status. Si usas Docker, añade docker compose ps para comprobar el mapeo real de 18789/18790.

Si no funcionó: no expongas el Gateway directo; usa reverse proxy/VPN/túnel con autenticación y revisa openclaw doctor. Los endpoints locales verificados son /healthz y /readyz; una IP pública no debería devolverlos.

API key commiteada a GitHub

Causa más probable: openclaw.json llegó al repositorio público

Comando copiable: Rota la API key inmediatamente en openrouter.ai > Settings > Keys. Luego añade openclaw.json a .gitignore.

Si no funcionó: usa SecretRefs, auth profiles o variables de entorno seguras; no pongas secretos en openclaw.json.

*Skill instalada sin auditar

Causa más probable: Confiaste en las reseñas (que pueden ser de bots)

Comando copiable: Antes de instalar: lee SKILL.md, revisa la ficha y auditorías de ClawHub, ejecuta openclaw skills search <slug> y pruébala en un agente separado antes de instalarla con openclaw skills install <slug>.

Si no funcionó: Tras ClawHavoc (febrero 2026), ClawHub aplica VirusTotal automático, pero no confíes ciegamente

47 warnings en openclaw doctor y los ignoras

Causa más probable: Te acostumbraste al ruido

Comando copiable: Revisa logs semanalmente. Programa openclaw doctor como cron semanal solo si cron carga la ruta correcta de OpenClaw. Si sale algo en rojo, investígalo en el momento.

Si no funcionó: (crontab -l 2>/dev/null; echo "0 9 * * 1 $(command -v openclaw) doctor >> ~/openclaw-doctor-$(date +\\%Y\\%m\\%d).log 2>&1") | crontab -

Sin backup del workspace y el VPS muere

Causa más probable: Nunca configuraste copias de seguridad

Comando copiable: rsync -avz ~/.openclaw/workspace/ ~/.openclaw/openclaw.json usuario@servidor-backup:~/backup-openclaw/

Si no funcionó: Como mínimo, copia ~/.openclaw/workspace/ y ~/.openclaw/openclaw.json a Drive/S3 semanalmente

16 — Certificados SSL (Traefik + Let's Encrypt)

Capítulos relacionados: Capítulo 5, Apéndice A

Diagnóstico rápido

El certificado SSL no se renueva automáticamente

Causa más probable: El archivo acme.json está corrupto o tiene permisos incorrectos

Comando copiable: cp /docker/traefik/acme.json "/docker/traefik/acme.json.$(date +%Y%m%d_%H%M%S).bak" && chmod 600 /docker/traefik/acme.json && docker compose logs --tail 100 traefik

Si no funcionó: docker compose logs -f traefik para verificar que regenera los certificados

Error de certificado en el navegador

Causa más probable: El dominio no apunta a la IP del VPS

Comando copiable: dig +short tu-dominio.com debe devolver la IP de tu VPS.

Si no funcionó: Revisa los registros DNS A/AAAA en tu proveedor de dominio (Cloudflare, Namecheap)

17 — Disco y Recursos del Sistema

Capítulos relacionados: Capítulo 5, Capítulo 6

Diagnóstico rápido

Disco lleno en el VPS

Causa más probable: Logs, Docker o temporales acumulados

Comando copiable: df -h, du -h -d1 /var /docker 2>/dev/null, docker system df y journalctl --disk-usage para medir antes de borrar. Limpia recursos no usados con docker system prune -f solo tras revisar qué servicios hay en el host, y logs antiguos con journalctl --vacuum-time=3d; evita borrar /tmp/* a ciegas.

Si no funcionó: Si tras limpiar queda < 20 % libre, amplía el disco en el panel del proveedor

Docker ocupa demasiado espacio

Causa más probable: Imágenes, contenedores parados, volúmenes huérfanos

Comando copiable: docker system df detalla el uso. Si aún falta espacio, revisa imágenes con docker image ls; evita docker system prune -a -f salvo como acción avanzada, con servicios críticos detenidos y en servidores que controles.

Si no funcionó: docker volume ls y, solo con confirmación humana, docker volume prune --filter "label!=keep". No borres volúmenes sin saber qué contienen.

Cuando nada de esto funcione

Has seguido todos los pasos y el problema persiste. Pasa esto antes de tirar la toalla:

Copia el error exacto. El mensaje literal, no tu interpretación. Pégalo en Google entre comillas. El 99 % de los errores ya tienen respuesta en Stack Overflow, GitHub Issues o el foro de OpenClaw.

Ejecuta openclaw doctor y guarda la salida. Cópiala a un archivo: openclaw doctor > ~/diagnostico.txt. Antes de pedir ayuda en Discord o Telegram, revisa y redacta tokens, rutas sensibles, dominios privados, IPs y claves. Ese archivo es oro, pero no debe llevar secretos.

Reinicia el Gateway. openclaw gateway restart. Suele arreglar más de lo que parece.

Busca en docs.openclaw.ai con el mensaje de error.

Pregunta en la comunidad. Discord y Telegram de OpenClaw tienen canales de ayuda. Lleva el diagnóstico de openclaw doctor preparado.

Y recuerda la regla más importante: respira. Todo lo que ves en rojo ya lo ha visto alguien antes que tú. No eres el primero ni serás el último. Lo vas a arreglar.

LAT3DEV