Construir un asistente personal con OpenClaw

OpenClaw es un gateway de WhatsApp + Telegram + Discord + iMessage para agentes Pi. Los plugins añaden soporte para Mattermost. Esta guía cubre la configuración como “asistente personal”: un número de WhatsApp dedicado que funciona como tu agente siempre disponible.

Seguridad ante todo

Le estás dando a un agente la capacidad de:

  • ejecutar comandos en tu máquina (según tu configuración de herramientas Pi)
  • leer y escribir archivos en tu workspace
  • enviar mensajes por WhatsApp/Telegram/Discord/Mattermost (plugin)

Empieza con prudencia:

  • Configura siempre channels.whatsapp.allowFrom (nunca dejes acceso abierto al mundo en tu Mac personal).
  • Usa un número de WhatsApp dedicado para el asistente.
  • Los heartbeats ahora se ejecutan por defecto cada 30 minutos. Desactívalos hasta que confíes en la configuración con agents.defaults.heartbeat.every: "0m".

Requisitos previos

  • OpenClaw instalado y con el onboarding completado: consulta Primeros pasos si aún no lo has hecho
  • Un segundo número de teléfono (SIM/eSIM/prepago) para el asistente

La configuración de dos teléfonos (recomendada)

Lo que buscas es esto:

flowchart TB
    A["<b>Tu teléfono (personal)<br></b><br>Tu WhatsApp<br>+1-555-YOU"] -- mensaje --> B["<b>Segundo teléfono (asistente)<br></b><br>WA del asistente<br>+1-555-ASSIST"]
    B -- vinculado vía QR --> C["<b>Tu Mac (openclaw)<br></b><br>Agente Pi"]

Si vinculas tu WhatsApp personal a OpenClaw, cada mensaje que recibas se convierte en “entrada del agente”. Eso rara vez es lo que quieres.

Inicio rápido en 5 minutos

  1. Vincula WhatsApp Web (muestra un QR; escanéalo con el teléfono del asistente):
openclaw channels login
  1. Inicia el Gateway (déjalo corriendo):
openclaw gateway --port 18789
  1. Coloca una configuración mínima en ~/.openclaw/openclaw.json:
{
  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}

Ahora envía un mensaje al número del asistente desde tu teléfono autorizado.

Cuando el onboarding termine, se abre automáticamente el dashboard y se imprime un enlace limpio (sin token). Si pide autenticación, pega el token de gateway.auth.token en los ajustes de Control UI. Para volver a abrirlo: openclaw dashboard.

Dale al agente un workspace (AGENTS)

OpenClaw lee las instrucciones operativas y la “memoria” desde su directorio de workspace.

Por defecto, OpenClaw usa ~/.openclaw/workspace como workspace del agente y lo crea automáticamente (junto con los archivos iniciales AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md) durante el setup o la primera ejecución del agente. BOOTSTRAP.md solo se crea cuando el workspace es completamente nuevo (no debería reaparecer después de eliminarlo). MEMORY.md es opcional (no se crea automáticamente); cuando está presente, se carga en las sesiones normales. Las sesiones de sub-agentes solo inyectan AGENTS.md y TOOLS.md.

Consejo: trata esta carpeta como la “memoria” de OpenClaw y conviértela en un repositorio git (idealmente privado) para que tu AGENTS.md y los archivos de memoria estén respaldados. Si git está instalado, los workspaces nuevos se inicializan automáticamente.

openclaw setup

Estructura completa del workspace y guía de respaldo: Workspace del agente Flujo de memoria: Memoria

Opcional: elige un workspace diferente con agents.defaults.workspace (acepta ~).

{
  agent: {
    workspace: "~/.openclaw/workspace",
  },
}

Si ya gestionas tus propios archivos de workspace desde un repositorio, puedes desactivar la creación de archivos de bootstrap por completo:

{
  agent: {
    skipBootstrap: true,
  },
}

La configuración que lo convierte en “un asistente”

OpenClaw viene con buenos valores por defecto para funcionar como asistente, pero normalmente querrás ajustar:

  • La persona e instrucciones en SOUL.md
  • Los valores por defecto de thinking (si lo deseas)
  • Los heartbeats (una vez que confíes en la configuración)

Ejemplo:

{
  logging: { level: "info" },
  agent: {
    model: "anthropic/claude-opus-4-6",
    workspace: "~/.openclaw/workspace",
    thinkingDefault: "high",
    timeoutSeconds: 1800,
    // Empieza en 0; actívalo después.
    heartbeat: { every: "0m" },
  },
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"],
      groups: {
        "*": { requireMention: true },
      },
    },
  },
  routing: {
    groupChat: {
      mentionPatterns: ["@openclaw", "openclaw"],
    },
  },
  session: {
    scope: "per-sender",
    resetTriggers: ["/new", "/reset"],
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 10080,
    },
  },
}

Sesiones y memoria

  • Archivos de sesión: ~/.openclaw/agents/<agentId>/sessions/{{SessionId}}.jsonl
  • Metadatos de sesión (uso de tokens, última ruta, etc.): ~/.openclaw/agents/<agentId>/sessions/sessions.json (legacy: ~/.openclaw/sessions/sessions.json)
  • /new o /reset inicia una sesión nueva para ese chat (configurable vía resetTriggers). Si se envía solo, el agente responde con un breve saludo para confirmar el reinicio.
  • /compact [instrucciones] compacta el contexto de la sesión y reporta el presupuesto de contexto restante.

Heartbeats (modo proactivo)

Por defecto, OpenClaw ejecuta un heartbeat cada 30 minutos con el prompt: Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK. Usa agents.defaults.heartbeat.every: "0m" para desactivarlo.

  • Si HEARTBEAT.md existe pero está efectivamente vacío (solo líneas en blanco y encabezados markdown como # Heading), OpenClaw omite la ejecución del heartbeat para ahorrar llamadas a la API.
  • Si el archivo no existe, el heartbeat se ejecuta igualmente y el modelo decide qué hacer.
  • Si el agente responde con HEARTBEAT_OK (opcionalmente con texto breve adicional; ver agents.defaults.heartbeat.ackMaxChars), OpenClaw suprime el envío de ese heartbeat.
  • Por defecto, el envío de heartbeats a destinos DM tipo user:<id> está permitido. Configura agents.defaults.heartbeat.directPolicy: "block" para suprimir el envío a destinos directos manteniendo activas las ejecuciones del heartbeat.
  • Los heartbeats ejecutan turnos completos del agente: intervalos más cortos consumen más tokens.
{
  agent: {
    heartbeat: { every: "30m" },
  },
}

Multimedia entrante y saliente

Los archivos adjuntos entrantes (imágenes/audio/documentos) se pueden exponer a tu comando mediante plantillas:

  • {{MediaPath}} (ruta local del archivo temporal)
  • {{MediaUrl}} (pseudo-URL)
  • {{Transcript}} (si la transcripción de audio está habilitada)

Archivos adjuntos salientes del agente: incluye MEDIA:<ruta-o-url> en su propia línea (sin espacios). Ejemplo:

Here's the screenshot.
MEDIA:https://example.com/screenshot.png

OpenClaw extrae estos marcadores y los envía como multimedia junto con el texto.

Checklist de operaciones

openclaw status          # estado local (credenciales, sesiones, eventos en cola)
openclaw status --all    # diagnóstico completo (solo lectura, se puede copiar y pegar)
openclaw status --deep   # añade sondas de health al gateway (Telegram + Discord)
openclaw health --json   # snapshot de health del gateway (WS)

Los logs se almacenan en /tmp/openclaw/ (por defecto: openclaw-YYYY-MM-DD.log).

Siguientes pasos

arrow_back
Anterior
Onboarding
Siguiente
Wizard CLI Reference
arrow_forward