gateway-watchdog

# Gateway Watchdog

Detect abnormal error patterns in the OpenClaw Gateway before they cause damage. Works with all channels: Telegram, WhatsApp, Discord, Slack, Signal, iMessage, Feishu, and more.

Born from a real incident: a silent `try-catch` caused 76,744 failed retries in 8 hours — undetected until the API quota was exhausted.

## What It Detects

| Category | Patterns |
|----------|----------|
| Rate limiting | HTTP 429, `rate.limit`, `too many requests` |
| Server errors | HTTP 5xx status codes |
| Auth/permission | HTTP 401/403, `unauthorized`, `forbidden`, `token expired` |
| Network errors | `ETIMEDOUT`, `ECONNREFUSED`, `ECONNRESET`, `ENOTFOUND`, `socket hang up` |
| Delivery failures | `sendMessage failed`, `deliver failed`, `fetch failed` |
| **Custom** | User-defined via `WATCHDOG_EXTRA_PATTERNS` env var |

### Smart Analysis
- **Error rate** (errors/min) — more meaningful than raw count
- **Spike detection** — alerts when errors jump 3x+ vs last check
- **Error concentration** — flags when 80%+ errors are one type (single fault source)

## Quick Start

```bash
bash scripts/gateway-watchdog.sh check     # silent unless errors exceed threshold
bash scripts/gateway-watchdog.sh verbose   # always outputs full report
bash scripts/gateway-watchdog.sh history   # show monitoring history
bash scripts/gateway-watchdog.sh trend     # last 24h error trend
```

### Heartbeat integration

Add to `HEARTBEAT.md`:

```markdown
## Gateway Error Monitoring (every heartbeat)
- Run `~/.openclaw/workspace/skills/gateway-watchdog/scripts/gateway-watchdog.sh check`
- If output is non-empty, report to user immediately
- No output = healthy, skip reporting
```

### Cron (optional)

```bash
openclaw cron add \
  --name "gateway-watchdog" \
  --schedule "*/30 * * * *" \
  --task "Run gateway-watchdog.sh verbose. If errors detected, notify user with the report." \
  --channel last
```

## Configuration

All via environment variables:

| Variable | Default | Description |
|------...