Event-Watcher

核心用法

Event Watcher 是一个面向 OpenClaw 的事件监听中间件，核心职责是按需唤醒 Agent——仅在特定事件到达时才触发会话，避免无意义的长轮询与 Token 消耗。

数据源支持：

• Redis Streams：支持消费者组（consumer group）与游标持久化，断点续传不丢事件。
• Webhook JSONL：通过 webhook_bridge.py 接收 HTTP 推送，追加到本地 JSONL 文件后由 watcher 消费。

事件处理流程：
1. Normalize：统一事件格式（来源无关的标准结构）。
2. Filter：JSON 规则引擎支持 AND/OR 组合与正则匹配，精确筛选目标事件。
3. Deduplication：基于 TTL 的去重缓存，防止重复触发。
4. Delivery：通过 sessions_send 或 agent_gate 路由到指定会话；支持自动解析最新会话（不强制指定 session_key）。
5. Ack/Retry：结构化日志记录接收/匹配/投递/失败计数，失败自动重试。

显著优点：

• 成本可控：无事件时不唤醒 Agent，Token 消耗趋近于零。
• 架构轻量：纯 Python 脚本，无需 systemd/pm2，nohup/tmux 即可常驻。
• 路由灵活：支持 Slack 频道、用户 DM 自动会话解析，配置简洁。
• 可观测性：内置计数器与结构化日志，便于监控事件漏斗。

潜在局限：

• 运维责任：Redis 连接稳定性、游标持久化、JSONL 文件轮转需自行维护。
• 并发规模：单进程设计，高吞吐场景需水平扩展（多 consumer group 分片）。
• 无内置 UI：配置与状态查看依赖文件/YAML，无管理界面。

适合人群：

• 需要事件驱动自动化的 OpenClaw 用户，尤其是希望按需计费、避免常驻 Agent的场景。
• 已有 Redis 或 Webhook 基础设施，愿意承担轻量运维的技术团队。

常规风险：

• 配置漂移：reply_to 格式错误（如漏写 channel: 前缀）导致投递失败。
• 权限遗漏：Slack 频道未加入 OpenClaw allowlist，消息静默丢弃。
• TTL 设置不当：去重窗口过长可能漏掉合法重复事件，过短则可能导致重复触发。
• 重试风暴：下游 Agent 异常时若未设置退避策略，可能形成重试循环。

核心用法

Event Watcher 是一款专为 OpenClaw 生态打造的事件监听与 Agent 唤醒工具。其核心工作流程分为三层：首先通过 Redis Streams 消费组或 Webhook JSONL 接收事件源数据；其次执行规范化、过滤、去重三重处理；最终通过 sessions_send 或 agent_gate 将匹配事件精准路由至目标会话，实现"无事件不唤醒"的按需计算模式。

配置层面采用 YAML 驱动，支持 JSON 规则过滤（含 AND/OR 逻辑与正则匹配）、TTL 去重、失败重试等机制。运行时推荐以后台任务形式启动（nohup/tmux），无需复杂进程管理。关键配置项包括 reply_channel（固定为 slack）、reply_to（channel:CXXXX 或 user:UXXXX 格式），且不应手动设置 `session_key`——系统会自动解析目标频道/用户的最新会话。

显著优点

1. 成本优化架构：零事件状态下零 Token 消耗，颠覆传统轮询模式的资源浪费。
2. 多源异构接入：统一支持 Redis Streams（企业级消息队列）与 Webhook JSONL（轻量级 HTTP 推送）。
3. 企业级可靠性：内置消费组持久化、消息去重、失败重试三重保障。
4. 会话智能路由：自动绑定 Slack 频道/用户与会话，无需硬编码 session_key。
5. 可观测性完善：结构化日志配合接收/匹配/投递/失败四类计数器，便于监控告警。
6. 安全编码实践：采用 yaml.safe_load 与 json.loads 避免反序列化漏洞，无硬编码敏感信息。

潜在局限

1. 生态依赖性强：深度绑定 OpenClaw CLI 与特定会话机制，迁移成本较高。
2. Slack 生态限定：当前仅原生支持 Slack 通道，多平台扩展需自行适配。
3. 配置门槛存在：YAML 规则语法、正则过滤、TTL 策略对非技术用户有一定学习曲线。
4. 输入验证待完善：Webhook payload 缺乏严格的 Schema 校验与大小限制。
5. ReDoS 风险：用户自定义正则表达式未设复杂度上限，极端情况下可能引发拒绝服务。

适合群体

• OpenClaw 重度用户：已构建 Slack 工作流，需事件驱动降低 Token 成本的技术团队。
• 运维自动化工程师：需要将 Redis Streams 或 Webhook 事件转化为 Agent 即时响应的场景。
• 成本敏感型组织：对 LLM Token 消耗有严格预算，追求"按需唤醒"架构的中小团队。

使用风险

| 风险类别 | 具体描述 | 缓释建议 |

|---------|---------|---------|

| 依赖可用性 | Redis 服务端或 OpenClaw CLI 故障将导致事件流中断 | 配置 Redis Sentinel 集群，监控 CLI 退出码 |

| ReDoS 攻击 | 恶意构造的复杂正则表达式可能导致 CPU 耗尽 | 文档警告+正则超时机制+模式白名单 |

| 路径遍历 | 配置文件路径可能包含 `../` 序列 | 启动前校验路径规范化结果 |

| 会话漂移 | 频道/用户会话过期或权限变更导致投递失败 | 定期检查 `openclaw.json` 通道白名单 |

| 资源泄漏 | 长期运行的后台任务可能积累内存 | 设置日志轮转与进程监控 |

整体而言，Event Watcher 是一款设计精良、安全可控的 OpenClaw 专属组件，适合技术成熟团队在生产环境部署，建议优先处理输入验证与路径遍历防护以增强鲁棒性。