Gateway Health Dashboard

Real-time monitoring and diagnostics CLI for OpenClaw gateway infrastructure. Zero dependencies, production-ready, extensible.

Why This Tool?

Running OpenClaw in production requires observability. This tool provides:

• Real-time monitoring of gateway health and response times
• Automatic alerting on failures, slowdowns, and anomalies
• Rich terminal UI for live dashboards
• Historical metrics export (JSON/CSV for analysis)
• Zero dependencies — runs on any Node.js environment
• Production-grade — used in homelab + enterprise deployments

Features

✅ Health Checks — HTTP status monitoring with configurable intervals
✅ Response Time Tracking — Min/max/avg metrics with alert thresholds
✅ Consecutive Failure Detection — Alert on repeated failures
✅ Metrics Export — JSON and CSV formats for integration
✅ CLI + Library — Use as terminal UI or programmatically
✅ Environment Config — GATEWAY_URL, CHECK_INTERVAL from env
✅ Lightweight — ~30KB unpacked, zero external dependencies

Installation

npm install -g gateway-health-dashboard

Or use locally:

npm install gateway-health-dashboard

Quick Start

Monitor Gateway in Real-time

gateway-dashboard monitor

Or with custom interval (check every 10 seconds):

GATEWAY_URL=http://192.168.1.100:18790 CHECK_INTERVAL=10000 gateway-dashboard monitor

Single Health Check

gateway-dashboard check

Returns exit code 0 if healthy, 1 if unhealthy (useful for CI/CD/cron).

Print Status Report

gateway-dashboard report

Export Metrics

Export metrics for integration with monitoring systems:

gateway-dashboard export-json /tmp/gateway-metrics.json
gateway-dashboard export-csv /tmp/gateway-metrics.csv

Usage as Library

const { GatewayHealthDashboard } = require('gateway-health-dashboard');

const dashboard = new GatewayHealthDashboard('http://localhost:18789');

// Single check
const result = await dashboard.getGatewayStatus();
console.log(result);
// {
//   success: true,
//   status: { statusCode: 200, responseTime: 145, timestamp: "...", ... },
//   duration: 145
// }

// Continuous monitoring
await dashboard.startMonitoring(5000); // Check every 5 seconds

// Get aggregated statistics
const summary = dashboard.getMetricsSummary();
// {
//   avg: 150,
//   min: 85,
//   max: 320,
//   count: 47,
//   successRate: "95.7"
// }

// Export for analysis
dashboard.exportMetrics('metrics.json');
dashboard.exportCSV('metrics.csv');

API Reference

GatewayHealthDashboard(url)

Constructor.

Parameters:

• url (string, optional) — Gateway endpoint. Default: http://localhost:18789

const dashboard = new GatewayHealthDashboard('http://192.168.1.100:18790');

getGatewayStatus()

Async method. Performs single health check.

Returns: Promise resolving to:

{
  success: boolean,
  status: { statusCode, responseTime, timestamp, ... },
  duration: number (milliseconds)
}

startMonitoring(interval)

Async method. Starts continuous monitoring loop.

Parameters:

• interval (number, optional) — Check interval in milliseconds. Default: 5000

Clears screen and displays live dashboard. Press Ctrl+C to stop.

getMetricsSummary()

Synchronous. Returns aggregated metrics from buffer.

Returns:

{
  avg: number,      // Average response time
  min: number,      // Minimum response time
  max: number,      // Maximum response time
  count: number,    // Total checks
  successRate: string  // Percentage (e.g., "95.7")
}

recordMetric(metric)

Synchronous. Manually record a metric.

Parameters:

• metric (object) — Metric data { duration, success, ... }

exportMetrics(filePath)

Synchronous. Export metrics as JSON.

Parameters:

• filePath (string, optional) — Output file path. Default: gateway-metrics.json

exportCSV(filePath)

Synchronous. Export metrics as CSV.

Parameters:

• filePath (string, optional) — Output file path. Default: gateway-metrics.csv

formatStatusReport()

Synchronous. Generate formatted status text.

Returns: String containing formatted report with alerts.

formatUptime(ms)

Synchronous. Format milliseconds as human-readable uptime.

Parameters:

• ms (number) — Milliseconds

Returns: String like "5d 3h", "2h 15m", "45s"

Environment Variables

• GATEWAY_URL — Gateway endpoint URL (default: http://localhost:18789)
• CHECK_INTERVAL — Check interval in milliseconds (default: 5000)

Example:

GATEWAY_URL=http://192.168.1.100:18790 CHECK_INTERVAL=10000 gateway-dashboard monitor

Use Cases

1. Development — Monitor Local Gateway

gateway-dashboard monitor

Watch real-time response times while developing agents.

2. CI/CD — Gateway Health Checks

gateway-dashboard check
echo $?  # Exit code 0 = healthy, 1 = unhealthy

Integrate into deployment pipelines:

if gateway-dashboard check; then
  echo "Gateway healthy, deploying..."
else
  echo "Gateway unhealthy, aborting deployment"
  exit 1
fi

3. Homelab Monitoring — 24/7 Dashboard

while true; do
  gateway-dashboard report
  sleep 60
done

Or export periodically for integration with Prometheus/Grafana:

# Cron: every 5 minutes
gateway-dashboard export-json /tmp/metrics.json

4. Troubleshooting — Historical Analysis

gateway-dashboard export-csv metrics.csv
# Analyze in Excel, Python, etc.

5. Production Alerting — Custom Scripts

const { GatewayHealthDashboard } = require('gateway-health-dashboard');
const dashboard = new GatewayHealthDashboard(process.env.GATEWAY_URL);

setInterval(async () => {
  const result = await dashboard.getGatewayStatus();
  
  if (!result.success) {
    // Send alert (email, Slack, webhook, etc.)
    sendAlert(`Gateway down: ${result.error}`);
  }
  
  if (result.duration > 2000) {
    // Send warning
    sendAlert(`Slow response: ${result.duration}ms`);
  }
}, 30000);

Performance & Reliability

• Response time: Typically 50-200ms per check
• Timeout: 5 seconds per request (configurable)
• Failure detection: Tracks consecutive failures automatically
• Memory: ~1KB per 100 metrics stored
• CPU: Negligible (single async request per interval)

Tested with:

• ✅ 1,000+ consecutive checks (24+ hour runs)
• ✅ Network latency up to 500ms
• ✅ Gateway response times 50-2000ms
• ✅ Connection failures and timeouts

Example Outputs

Monitor Command

╔════════════════════════════════════════════════════════╗
║     GATEWAY HEALTH DASHBOARD                           ║
╚════════════════════════════════════════════════════════╝

Status:              ✅ HEALTHY
Timestamp:           2/25/2026, 10:15:30 AM
Gateway URL:         http://localhost:18789
Response Time:       142ms
Consecutive Fails:   0
Status Code:         200
Version:             2026.2.22

Metrics Summary (last 47 checks):
  Average Response:   150ms
  Min Response:       85ms
  Max Response:       320ms
  Success Rate:       95.7%

Iteration: 47
Press Ctrl+C to stop monitoring

Export JSON

{
  "exportedAt": "2026-02-25T10:15:30.000Z",
  "gateway": "http://localhost:18789",
  "summary": {
    "avg": 150,
    "min": 85,
    "max": 320,
    "count": 47,
    "successRate": "95.7"
  },
  "history": [
    {
      "timestamp": 1740467730000,
      "duration": 142,
      "success": true,
      "statusCode": 200
    },
    ...
  ]
}

Troubleshooting

"Cannot find module" error

npm install -g gateway-health-dashboard
# Or locally:
npm install gateway-health-dashboard

Timeout or connection refused

Check gateway is running:

curl http://localhost:18789/api/status

Specify correct URL:

GATEWAY_URL=http://192.168.1.100:18790 gateway-dashboard check

Too many alerts

Increase check interval:

CHECK_INTERVAL=30000 gateway-dashboard monitor  # 30 seconds

License

MIT

Author

botfit ([email protected])

Repository

https://github.com/openclaw/gateway-health-dashboard

Contributing

Issues and PRs welcome!

Related Tools

• gateway-metrics-parser — Parse and aggregate gateway metrics
• llm-token-budget — Token cost tracking
• cron-monitor-js — Cron job health monitoring
• openclaw-config-validator — Validate OpenClaw configs

Made for homelab enthusiasts and OpenClaw users worldwide 🌍