106 lines
3.1 KiB
Markdown
106 lines
3.1 KiB
Markdown
# 🦞 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)
|