Strong support + use case: Event-driven agent notifications

强烈支持 + 使用场景：事件驱动的 Agent 主动通知

This PR addresses a critical gap. I built an entire external events-framework (1500 lines of Python: event inbox → router → rate-limit/dedupe/quiet-hours → Telegram) just because OpenClaw has no native event-driven hook for "something happened → notify user."

这个 PR 解决了一个关键缺口。我构建了一整套外部 events-framework（1500 行 Python：事件收件箱 → 路由器 → 限频/去重/静默时段 → Telegram），仅仅因为 OpenClaw 没有原生的事件驱动钩子。

My use case / 我的使用场景

I run a multi-agent system (1 PM + 8 sub-agents). When sub-agents complete work, cost thresholds are hit, or errors occur, I need immediate, deduplicated, rate-limited notifications — not cron polling every N minutes.

我运行一个多 Agent 系统（1 个项目经理 + 8 个子 Agent）。当子 Agent 完成工作、费用阈值触发或发生错误时，我需要即时、去重、限频的通知——而不是 cron 每 N 分钟轮询。

The message:received hook is the foundation for making OpenClaw truly event-driven rather than poll-driven.

message:received 钩子是让 OpenClaw 从轮询驱动变为事件驱动的基础。

On the Greptile performance concern / 关于 Greptile 的性能顾虑

Greptile flagged that message:received is awaited in the hot path. Hooks should be fire-and-forget to avoid blocking:

triggerInternalHook(event).catch(err => logger.warn("hook error", err));

Note on competing PRs / 关于竞争 PR

I see #7545 and #9387 also implement similar functionality. It would be great if maintainers could signal which approach they prefer so the community can consolidate effort.

我注意到 #7545 和 #9387 也实现了类似功能。希望维护者能表明倾向哪种方案，让社区集中力量。

Thanks for the detailed support @Zjianru — great to see someone else hitting the same wall. Your event framework sounds like exactly the kind of thing that should be built-in rather than bolted on.

On the performance concern: the current code already uses fire-and-forget with error isolation (void triggerInternalHook(...).catch(...)) — addressed in a follow-up commit after the Greptile review. Hooks will not block the message pipeline.

Regarding the competing PRs (#7545, #9387) — here is how they compare:

This PR fires at the dispatch level (dispatch-from-config.ts) so it covers all channels without per-channel wiring. The message:transcribed hook is unique here — it fires after audio transcription completes, which is useful for workflows that need the actual transcript content (e.g., echoing transcripts back to the user before the agent responds).

Would love to see maintainers weigh in on which direction they prefer so effort can consolidate.

Technical suggestions for the two missing capabilities / 关于两个缺失能力的技术建议

Hi @Drickon, thanks again for the thorough comparison table — it really clarifies the landscape. I noticed two gaps in this PR compared to the other approaches, and wanted to offer some concrete suggestions.

感谢你提供的详细对比表，非常清晰。我注意到相比其他方案，这个 PR 还有两个能力缺口，想提供一些具体的技术建议。

1. message:sent hook — recommended addition / 建议补充

Since this PR already fires hooks at the dispatch level (dispatch-from-config.ts), adding a message:sent hook at the dispatch outbound path should be a natural extension — same fire-and-forget pattern, just triggered after the agent's reply is delivered to the channel adapter.

既然这个 PR 已经在 dispatch 层触发 hooks，在 dispatch 出站路径 添加 message:sent hook 应该是自然延伸——同样的 fire-and-forget 模式，只是在 agent 回复投递到渠道适配器之后触发。

Use cases / 使用场景:

• Audit logging (record every outbound message)
• Post-reply workflows (e.g., update status, trigger follow-up tasks)
• Analytics (response time tracking, message volume)

This would close the gap with #9387 while keeping the clean dispatch-level architecture.

这样可以补齐与 #9387 的差距，同时保持干净的 dispatch 层架构。

2. Message interception (modify/skip) — suggest keeping it separate / 建议作为独立 feature

The "modify/skip messages" capability from #7545 is fundamentally different from fire-and-forget hooks — it changes the hook semantics from notification to middleware/interceptor, which requires:

#7545 的"修改/跳过消息"能力与 fire-and-forget hooks 有本质区别——它将 hook 语义从通知变成了中间件/拦截器，这需要：

• Synchronous waiting for hook return values (introduces latency)
• Error handling for interceptor failures (what if the hook crashes — drop the message or pass through?)
• Ordering guarantees when multiple interceptors are registered

I'd suggest not mixing this into the current PR. It deserves its own design discussion — perhaps as a separate message:intercept or message:beforeProcess hook with explicit opt-in semantics, so the fire-and-forget hooks remain lightweight and non-blocking.

建议不要混入当前 PR。这值得独立的设计讨论——也许作为单独的 message:intercept 或 message:beforeProcess hook，使用显式的 opt-in 语义，让 fire-and-forget hooks 保持轻量和非阻塞。

Thanks for driving this forward — your dispatch-level approach is the cleanest of the three PRs in my view. Happy to contribute further if it helps move things along. 🙂

感谢你推动这件事——在我看来，你的 dispatch 层方案是三个 PR 中最干净的。如果能帮上忙，我很乐意为社区继续贡献。

Thanks for the suggestions! Added message:sent in the latest commit.

Agreed that interception/middleware should be a separate PR. Your multi-agent use case would give you better perspective on the design decisions there. If you're interested in taking that on, go for it. Just drop a comment here or open an issue so we can coordinate.

Appreciate the input!

👋 Just wanted to add a +1 for this PR — we have a real use case waiting on it.

Use case: Auto-transcription of inbound audio messages via a workspace hook. Currently audio files arrive as attachments and can get lost in context compaction before processing. The message:transcribed hook would let us reliably capture transcripts for logging, memory, or forwarding to other channels.

The implementation looks solid (fire-and-forget, channel-agnostic, good test coverage). Would love to see this merged! 🙏

this is exactly what we proposed in #14539. been running all of these events (received + preprocessed + sent) in production for 8+ days — 550+ events, 2 bots, 4 groups, zero crashes.

a few things from production experience:

1. groupId in message:sent — critical. without it, received and sent events for the same conversation get different identifiers, making correlation impossible. detailed writeup: feat(hooks): add message:received and message:sent hook events #6797 (comment)

2. message:transcribed as separate event — smart decision. we initially combined it into preprocessed, but having a dedicated transcription event is cleaner for hooks that only care about audio (like @j0nscalet's use case).

3. fire-and-forget + error isolation — confirmed working in production. hook errors never broke message delivery.

production hooks built on this:

• memory logger (canonical append-only jsonl, feeds embeddings)
• output DLP (regex + entropy scan on sent, catches leaked API keys)
• multi-bot sync (events forwarded to shared hub, 2 bots see each other's conversations)

reference hook implementation: https://github.com/matskevich/openclaw-infra/tree/main/hooks/memory-logger

happy to help test or review.