> ## Documentation Index
> Fetch the complete documentation index at: https://docs.steadwing.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenClaw

> OpenAlerts monitors your OpenClaw AI messaging gateway in real-time, detecting LLM errors, gateway outages, stuck sessions, and cost spikes with a live dashboard and Telegram/webhook alerts.

[OpenClaw](https://github.com/openclaw/openclaw) is an open-source AI messaging gateway that connects to WhatsApp, Telegram, Discord, Slack, iMessage, and other messaging channels. It routes conversations to your AI agents and includes a plugin system for extending functionality.

## How do I install OpenClaw?

```bash theme={null} theme={null}
npm install -g openclaw@latest

# Run the interactive setup wizard
openclaw onboard --install-daemon
```

See the [OpenClaw getting started guide](https://docs.openclaw.ai/start/getting-started) for details.

## How do I set up OpenAlerts for OpenClaw?

AI agents fail silently — LLM errors, stuck sessions, gateway outages — nobody knows until a user complains. [OpenAlerts](https://github.com/steadwing/openalerts) is a standalone monitoring daemon that connects to your OpenClaw gateway in real-time, fires alerts when something goes wrong, and serves a live dashboard. No code changes to OpenClaw needed — runs as a separate process alongside it.

### Install

```bash theme={null} theme={null}
npm install -g @steadwing/openalerts
```

<Info>
  Requires **Node.js 22.5.0 or later** — uses the built-in `node:sqlite` module, so there are no native builds or binaries to compile.
</Info>

### Quick Start

```bash theme={null} theme={null}
# 1. Create default config (auto-detects your OpenClaw gateway token)
openalerts init

# 2. Edit config to add your alert channel
#    ~/.openalerts/config.json

# 3. Start monitoring
openalerts start
```

Dashboard opens at **[http://127.0.0.1:4242](http://127.0.0.1:4242)** — the gateway overlay dismisses automatically once connected.

The gateway token is auto-detected from `gateway.auth.token` in `~/.openclaw/openclaw.json` — no manual copy needed.

### Channels

Configure at least one channel in `~/.openalerts/config.json`. Falls back to `console` if none are set.

```json theme={null} theme={null}
{
  "channels": [
    { "type": "telegram", "token": "BOT_TOKEN", "chatId": "CHAT_ID" },
    { "type": "webhook", "webhookUrl": "https://your-endpoint" },
    { "type": "console" }
  ]
}
```

### Alert Rules

10 rules run against every event in real-time. All thresholds and cooldowns are configurable.

| Rule                | Triggers when                           | Default threshold | Default cooldown |
| ------------------- | --------------------------------------- | ----------------- | ---------------- |
| `infra-errors`      | Infrastructure errors in 1 min window   | 1                 | 15 min           |
| `llm-errors`        | LLM/agent errors in 1 min window        | 1                 | 15 min           |
| `tool-errors`       | Tool execution failures in 1 min window | 1                 | 15 min           |
| `heartbeat-fail`    | Consecutive heartbeat failures          | 3                 | 30 min           |
| `session-stuck`     | Session idle too long                   | 120s              | 30 min           |
| `high-error-rate`   | Error rate of last 20 calls             | 50%               | 30 min           |
| `queue-depth`       | Items piling up in delivery queue       | 10                | 15 min           |
| `gateway-down`      | No heartbeat from watchdog              | 30s               | 60 min           |
| `cost-hourly-spike` | LLM cost per hour                       | \$5               | 30 min           |
| `cost-daily-budget` | LLM cost per day                        | \$20              | 6 h              |

To tune rules:

```json theme={null} theme={null}
{
  "rules": {
    "llm-errors": { "threshold": 5 },
    "gateway-down": { "enabled": false },
    "heartbeat-fail": { "cooldownMinutes": 60 }
  }
}
```

Set `"quiet": true` at the top level for log-only mode (no alerts sent).

### Dashboard

A real-time web dashboard is served at **[http://127.0.0.1:4242](http://127.0.0.1:4242)** after running `openalerts start`:

| Tab                | What it shows                                                    |
| ------------------ | ---------------------------------------------------------------- |
| **Overview**       | Gateway health log, live activity feed, 24h stats, recent alerts |
| **Workspaces**     | Per-agent SOUL.md, HEARTBEAT.md, MEMORY.md previews              |
| **Alerts**         | Full alert history with severity, rule ID, fingerprint           |
| **Sessions**       | Active sessions with status, token counts, cost                  |
| **Live Monitor**   | Real-time per-run timeline — steps, tool calls, LLM responses    |
| **Cron Jobs**      | Scheduled job status, last/next run, consecutive errors          |
| **Diagnostics**    | Raw engine event log                                             |
| **Delivery Queue** | Pending/failed alert delivery items                              |

### CLI

| Command             | Description                                          |
| ------------------- | ---------------------------------------------------- |
| `openalerts init`   | Create default config at `~/.openalerts/config.json` |
| `openalerts start`  | Start the monitoring daemon                          |
| `openalerts status` | Print live engine state (daemon must be running)     |
| `openalerts test`   | Fire a test alert through all configured channels    |

`openalerts start` accepts `--port N` (default `4242`) and `--config PATH` (default `~/.openalerts/config.json`).

Need additional help? Please reach out to us at [hello@steadwing.com](mailto:hello@steadwing.com)