event-watcher

What This Skill Does

The Event Watcher skill is a robust, lightweight infrastructure component for OpenClaw that serves as a bridge between external data sources and your AI agent sessions. It allows your agent to remain idle and cost-effective, consuming zero tokens until specific criteria are met. The skill monitors Redis Streams and webhook endpoints, ingesting event data, applying sophisticated regex-based filtering, and managing deduplication. Once a matching event is identified, it automatically routes the payload to the most recent session using the internal messaging bus, ensuring the agent only wakes when it has relevant work to perform.

Installation

To integrate this skill into your environment, run the following command from your terminal within the OpenClaw environment: clawhub install openclaw/skills/skills/solitaire2015/event-watcher

Ensure that you have the necessary Python dependencies by running pip install -r scripts/requirements.txt. The tool requires a background process to remain active, so initiate it via python scripts/watcher.py in a persistent terminal session or your preferred task manager.

Use Cases

• Real-time Monitoring: Watch for critical system alerts or infrastructure health checks from Redis streams and immediately notify a slack channel.
• Automated Webhook Responses: Trigger custom AI workflows when external services (like GitHub or Stripe) send payloads to your webhook listener.
• Deduplication Logic: Prevent AI "chat spam" by using the built-in TTL dedupe, ensuring that if multiple identical events occur within a short window, the agent is only triggered once.
• Event Routing: Dispatch events directly to specific user DMs or project-specific Slack channels using the reply_to configuration parameter.

Example Prompts

1. "Monitor the 'system-alerts' Redis stream for any message containing 'CRITICAL' and post a summary to the #ops-alerts channel."
2. "Set up a webhook watcher that listens for incoming JSONL payloads from our CI/CD pipeline and alerts the team if a build failure occurs."
3. "Filter incoming events from the webhook source to only include payloads where 'user_id' matches our VIP whitelist, then route them to the active support session."

Tips & Limitations

• Prompt Safety: By default, the watcher injects a security header into payloads. Unless you fully trust the event source, keep wake.add_source_preamble enabled to prevent instruction injection.
• Configuration: Always store your configuration in the recommended {baseDir}/config/ directory to prevent path drift. Refer to references/CONFIG.md for specific key-value pairs regarding filtering logic.
• Routing: Avoid hardcoding routing instructions into your agent prompts. Instead, use the watcher's reply_channel and reply_to settings to define the destination. This separation of concerns keeps your agent focused on processing logic rather than transport configuration.
• Resource Management: While lightweight, ensure your Redis instance is reachable and the webhook_bridge.py is correctly configured to write to the appropriate JSONL file, as this is the primary bottleneck for data ingestion.