Channels

Agent Heartbeat

Name: Agent Heartbeat
Author: elsagrao

By elsagrao 👁 57 views ▲ 0 votes

Monitor de heartbeat para agentes OpenClaw: avisa por Discord si tu agente deja de responder. Backend + plugin nativo de OpenClaw.

GitHub

Install

npm install --ignore-scripts

README

# Agent Heartbeat (plugin nativo de OpenClaw)

Avisa por Discord si tu agente OpenClaw deja de responder. Zero-config de
verdad: instalas el plugin, pegas tu webhook de Discord, y ya está — no hace
falta tocar el código del agente.

Este plugin es la "distribución nativa" del backend
[Agent Heartbeat](../README.md). En vez de que cada desarrollador tenga que
copiar `client.py` y llamarlo a mano, el propio plugin:

1. Al arrancar el gateway de OpenClaw (`activation.onStartup: true`), crea un
   monitor automáticamente contra el backend (una sola vez; guarda el token en
   `stateDir/monitor.json` para no duplicar monitores en reinicios).
2. Lanza un ping periódico en background (`api.registerService`) con el
   intervalo que configures.
3. Si el agente deja de pingear (proceso caído, máquina apagada, gateway
   colgado), el backend manda el aviso 🔴 al webhook de Discord que
   configuraste.

## Instalación (para quien use el plugin)

```bash
openclaw plugins install clawhub:<org>/agent-heartbeat
```

Y en la config de OpenClaw:

```json5
{
  plugins: {
    entries: {
      "agent-heartbeat": {
        config: {
          discordWebhookUrl: "https://discord.com/api/webhooks/xxx/yyy",
          intervalSeconds: 300,
          graceSeconds: 120
        }
      }
    }
  }
}
```

Con eso ya está. No hace falta escribir ni una línea de código en el agente.

## Desarrollo

```bash
npm install --ignore-scripts   # openclaw exige Node 24.16+/26.1+; --ignore-scripts evita el gate de instalación si tu Node es mas viejo
npm run typecheck
npm run build                  # compila src/index.ts -> dist/index.js
npx clawhub package validate . # valida el manifest + build con el Plugin Inspector
```

Validado con el Plugin Inspector real de ClawHub: `PASS`, 0 breakages, 0
warnings (ver `reports/plugin-inspector-report.md`).

## Publicar en ClawHub (pendiente: requiere cuenta propia)

```bash
clawhub login
clawhub package publish . --dry-run
clawhub package publish .
```

## Importante antes de publicar de verdad

`DEFAULT_BACKEND_URL` en `src/index.ts` apunta a
`https://agent-heartbeat.fly.dev`, que es un placeholder hasta que el backend
esté desplegado de verdad (ver el Dockerfile/fly.toml en la carpeta padre).
Actualiza esa constante con la URL real de Fly.io/Railway antes de publicar,
o el plugin no podrá crear monitores. Quien se auto-hospede el backend puede
sobreescribirlo con la opción de config `backendUrl`.

channels