gateway-watchdog

What This Skill Does

The gateway-watchdog is an essential diagnostic utility for the OpenClaw ecosystem, designed to monitor the health and performance of the OpenClaw Gateway. By scanning system logs for specific patterns of failure, it provides proactive alerting against service disruptions before they escalate into full-scale outages. It excels at detecting rate-limiting triggers (such as 429 errors), network connectivity issues (ETIMEDOUT, ECONNRESET), server-side instability (5xx codes), and authentication failures across all integrated messaging channels including Telegram, WhatsApp, Discord, Slack, and Signal.

Unlike standard monitoring tools, the watchdog uses smart analysis to track errors per minute rather than just raw counts, allowing it to distinguish between trivial noise and genuine system spikes. It employs a spike detection algorithm that alerts when errors jump beyond a configurable ratio compared to the previous monitoring window, and it identifies error concentration, flagging scenarios where a single fault source accounts for the majority of issues. This ensures you are notified immediately when a silent failure, like an unhandled exception or a drained API quota, begins to impact your operations.

Installation

To install the gateway-watchdog, use the clawhub command-line interface provided in the OpenClaw environment:

clawhub install openclaw/skills/skills/guoqunabc/gateway-watchdog

Once installed, you can configure the watchdog by setting environment variables such as WATCHDOG_THRESHOLD to determine when an alert triggers. For persistent monitoring, we recommend adding the gateway-watchdog.sh check command to your HEARTBEAT.md file, or scheduling it as a recurring task using the OpenClaw cron manager. This ensures your gateway state is audited every 30 minutes, keeping your communication channels running smoothly without requiring manual oversight.

Use Cases

• Proactive Health Monitoring: Automatically detecting when an API quota is nearing exhaustion to prevent service suspension.
• Rapid Debugging: Identifying the root cause of connectivity issues by parsing logs for specific network-level errors or protocol timeouts.
• Integration Stability: Verifying that new channel integrations (e.g., adding a new Feishu bot) are not immediately encountering auth or permission errors.
• Trend Analysis: Reviewing historical error logs to identify recurring patterns that may coincide with specific times of day or high-traffic spikes.

Example Prompts

1. "OpenClaw, is the Gateway currently healthy? Run a diagnostic check for any recent error spikes."
2. "I'm seeing frequent timeouts with my Discord channel. Can you use the gateway-watchdog to check the logs for common network errors?"
3. "Show me the last 24-hour error trend report for the Gateway to see if we've been hitting any rate limits lately."

Tips & Limitations

• Threshold Tuning: If you receive too many false positives, increase the WATCHDOG_THRESHOLD variable in your environment configuration.
• Custom Patterns: Utilize the WATCHDOG_EXTRA_PATTERNS variable to track specific application-level error codes unique to your custom integrations or complex bot logic.
• State Management: The watchdog relies on local state files. Ensure the OpenClaw user has write permissions to ~/.local/state/gateway-watchdog/ to ensure logs and history remain accurate. Note that this skill does not automatically restart the Gateway; it is strictly an analysis and reporting tool designed to inform the user of necessary manual or automated interventions.