event-watcher

📡 事件驱动的智能代理唤醒器

OpenClaw 生态的事件监听技能,通过 Redis Streams 和 Webhook 实现条件触发,无事件时零 token 消耗,精准唤醒 Agent 处理实时数据流。

收藏
1.9k
安装
960
版本
v1.0.1
CLS 安全性认证2026-05-21
点击查看完整报告 >

使用说明

Event Watcher 是 OpenClaw 生态中的轻量级事件监听技能,专为需要响应实时数据流的场景设计。它通过监听 Redis Streams 和 Webhook JSONL 数据源,仅在匹配预设条件的事件到达时才唤醒 OpenClaw Agent 进行处理,实现"无事件不唤醒"的精准触发模式,有效避免无效轮询带来的 Token 消耗。

核心用法围绕配置文件展开。用户需编写 YAML 格式的 watcher 配置,定义 Redis Stream 消费者组或 Webhook 端点,通过 JSON 规则(支持 AND/OR 逻辑和正则表达式)设置事件过滤条件。配置中指定 reply_channelreply_to 目标(Slack 频道或用户),无需显式设置 session_key,系统会自动解析最新会话。运行时通过 nohuptmux 后台执行 watcher.py 脚本,持续监听直至收到终止信号。

显著优点包括极致的成本控制和灵活的集成能力。基于事件的触发机制确保没有匹配事件时 Agent 保持休眠,大幅降低 LLM Token 消耗。内置的去重机制(TTL 可配置)防止重复处理,自动重试和死信队列保障消息可靠投递。同时支持会话路由自动解析,简化了多频道部署的复杂度,并提供结构化日志和计数器便于监控。

潜在局限性主要体现在基础设施依赖和来源可信度。该技能强依赖 Redis 服务作为消息队列,需要额外的运维成本。作为 T3 级个人开发者作品,缺乏官方组织背书,在企业级生产环境中可能需要额外的代码审计。此外,Python 环境依赖(redis, pyyaml)和本地文件系统访问增加了部署复杂度,且依赖版本未锁定可能影响可复现性。

适合的目标群体包括:使用 OpenClaw 构建自动化工作流的开发者、需要基于 Redis Streams 实现事件驱动的 DevOps 工程师、以及希望将 Webhook 数据实时接入 Slack 工作区的运营团队。对于需要 7×24 小时监听外部事件并触发 AI 处理的场景尤为适用。

使用风险主要涉及数据隐私和执行安全。技能默认读取本地 ~/.openclaw/sessions/sessions.json 文件(可通过 disable_session_store_lookup 禁用),且使用 subprocess.run 执行 openclaw CLI 命令。事件 payload 会被转发至配置的 Slack 频道,需确保 openclaw.json 中的频道允许列表已正确配置,避免信息泄露。虽然代码本身无注入漏洞,但建议对不可信来源的事件数据保持警惕,保持默认的 add_source_preamble 安全头开启状态以防止 prompt 注入。

安全解读

核心用法

event-watcher 是一个轻量级事件监听 Skill,专为 OpenClaw 生态设计。其核心工作流为:订阅事件源 → 匹配过滤规则 → 去重 → 路由唤醒目标会话

数据源支持

  • Redis Streams:通过消费者组实现持久化订阅,支持断点续传
  • Webhook JSONL:内置 webhook_bridge.py 接收 HTTP 请求并追加至本地日志文件

关键配置要点

  • 路由策略:默认自动解析 channel:Cxxxxuser:Uxxxx 的最新活跃会话,无需硬编码 session_key
  • 过滤规则:支持 JSON 路径表达式 + AND/OR 组合 + 正则匹配
  • 去重机制:基于事件指纹的 TTL 缓存,防止重复唤醒

显著优点

1. 成本精准控制:"无事件不唤醒"架构,避免空闲轮询导致的 Token 浪费
2. 企业级可靠性:内置消费者组、失败重试、结构化计数器,适合生产环境

3. 低运维负担:单文件 Python 脚本即可运行,无需 systemd/pm2 等复杂部署

4. 安全默认:自动为不可信来源添加安全前缀,防止 prompt 注入攻击

潜在局限

  • 子进程依赖:唤醒 Agent 依赖本地 openclaw CLI 调用,跨平台部署需预装环境
  • 会话存储耦合:默认读取 ~/.openclaw/sessions/ 目录,多用户场景需显式禁用 disable_session_store_lookup
  • Redis 单点:当前仅支持 Redis Streams,未内置 Kafka/RabbitMQ 等多元队列适配
  • 无内置 Web UI:监控依赖日志解析或外部指标采集工具

适合人群

  • 需要将外部系统事件(CI/CD、监控告警、业务审批流)接入 OpenClaw 工作流的自动化工程师
  • 运行长期监听任务但希望严格管控 Token 消耗的成本敏感型团队
  • 已有 Redis 基础设施、寻求轻量级事件总线的 OpenClaw 用户

常规风险

| 风险项 | 级别 | 说明 |
|--------|------|------|
| 子进程执行 | 中等 | `subprocess.run()` 调用本地 CLI,参数经模板渲染,需防范事件 payload 中的 shell 元字符 |
| 敏感文件访问 | 中等 | 默认读取用户主目录下的会话存储文件,多租户环境建议显式禁用 |
| 环境变量泄露 | 低 | `REDIS_URL` 可能含密码,需避免写入共享日志或 shell history |

使用建议

1. 生产部署时设置 disable_session_store_lookup: true,改用显式 session_key 或 API 查询
2. 为 Webhook 接收端配置 IP 白名单或签名验证,防止伪造事件

3. 定期检查 watcher.py--dry-run 模式输出,验证过滤规则准确性

4. 建议配合 Redis TLS 模式,加密传输中的事件 payload

event-watcher 内容

examples文件夹
references文件夹
scripts文件夹
sources文件夹
手动下载zip · 14.4 kB
event_watcher.yamltext/plain
请选择文件