# 🦞 openclaw-watchdog

A standalone watchdog service for [OpenClaw](https://openclaw.dev) that monitors the gateway, auto-recovers from crashes, and sends Discord alerts when things go sideways.

## What It Does

- **Health monitoring** — Polls the gateway health endpoint at a configurable interval
- **Auto-restart** — Restarts the gateway on first failure detection
- **Config rollback** — Reverts to last-known-good config if a simple restart doesn't work
- **Discord SOS alerts** — Sends a detailed alert with SSH instructions when all recovery fails
- **Recovery notifications** — Lets you know when the gateway comes back online
- **No spam** — Only alerts once per incident

## Recovery Flow

```
Health check fails
       │
       ▼
  ┌─────────────┐
  │ Stage 1:    │──→ Simple restart
  │ Restart     │
  └──────┬──────┘
         │ still failing
         ▼
  ┌─────────────┐
  │ Stage 2:    │──→ Revert config to last-known-good + restart
  │ Rollback    │
  └──────┬──────┘
         │ still failing
         ▼
  ┌─────────────┐
  │ Stage 3:    │──→ Discord SOS with hostname & SSH instructions
  │ SOS Alert   │
  └─────────────┘
```

When the gateway recovers at any point, a ✅ recovery message is sent.

## Prerequisites

- [OpenClaw](https://openclaw.dev) installed with `openclaw` CLI available
- Linux with systemd
- `curl` and `jq`
- Discord bot token (optional, for alerts)

## Quick Install

```bash
git clone https://github.com/jlgrimes/openclaw-watchdog.git
cd openclaw-watchdog
chmod +x setup.sh watchdog.sh
./setup.sh
```

The installer will:
1. Copy `watchdog.sh` to `~/.openclaw/`
2. Create a config file at `~/.openclaw/watchdog.env`
3. Set up and start a systemd service

## Configuration

All settings live in `~/.openclaw/watchdog.env` (created by the installer):

| Variable | Default | Description |
|---|---|---|
| `HEALTH_URL` | `http://localhost:3000/health` | Gateway health endpoint |
| `CHECK_INTERVAL` | `30` | Seconds between health checks |
| `FAIL_THRESHOLD` | `3` | Consecutive failures before SOS |
| `OPENCLAW_CONFIG_PATH` | `~/.openclaw/config.yaml` | Path to OpenClaw config |
| `DISCORD_CHANNEL_ID` | *(none)* | Discord channel for alerts |
| `DISCORD_BOT_TOKEN` | *(none)* | Discord bot token for alerts |

After editing, restart the service:

```bash
sudo systemctl restart openclaw-watchdog
```

## Manual Usage

You can also run the watchdog directly:

```bash
export DISCORD_BOT_TOKEN="your-token"
export DISCORD_CHANNEL_ID="your-channel-id"
./watchdog.sh
```

## Managing the Service

```bash
sudo systemctl status openclaw-watchdog    # Check status
sudo systemctl restart openclaw-watchdog   # Restart
sudo systemctl stop openclaw-watchdog      # Stop
tail -f ~/.openclaw/watchdog.log           # View logs
```

## License

[MIT](LICENSE)

## Credits

Built by **Jared Grimes** and **Claw 🦞** (an OpenClaw AI assistant)