犀利豆的博客 ·

Claude Code Tools 研究系列（十三）—— Monitor：等待事件发生

💡 原文中文，约12700字，阅读约需31分钟。

📝

内容提要

Monitor是Claude Code的事件流监听工具，与Cron（时钟驱动）和Bash后台（单次通知）互补。它通过shell命令或WebSocket持续监听，每行stdout或文本帧即一个事件，支持过滤、超时和持久模式。设计强调事件驱动、避免轮询，并内置缓冲处理、速率限制和“沉默非成功”的观测哲学，让Claude被动接收外部变化，实现高效异步等待。

🔎

延伸解读

事件驱动 vs 轮询：Monitor 的核心价值

Monitor 的设计核心是事件驱动，与 Cron 的时钟驱动和 Bash 后台的单次通知形成互补。它通过持续监听 stdout 或 WebSocket 帧，让 Claude 被动接收外部变化，避免轮询带来的延迟和上下文消耗。文章强调，对于“等某件事发生”的场景，轮询不仅延迟高，还会浪费 context，而 Monitor 能实现即时感知，是异步等待的高效原语。

过滤器的关键性：沉默非成功

Monitor 的过滤器设计至关重要，官方 prompt 强调“silence is not success”，即过滤器必须覆盖所有终态，包括失败信号。如果只匹配成功标志，任务崩溃时可能静默，与“仍在运行”无法区分。文章建议在设置过滤器前自问：如果进程现在崩溃，我的过滤器会输出吗？这体现了 SRE 的观测哲学，确保监控的完备性。

WebSocket 支持：消除脆弱性的设计

Monitor 内置 WebSocket 作为一等数据源，而非依赖 websocat 命令行，这避免了额外进程、shell escape 和缓冲问题。文章认为这是超出预期的设计，体现了对 agent-to-agent 通信、订阅式部署事件等场景的预判。这种设计减少了工具链的脆弱性，让事件流接入更稳定。

速率限制与批处理：保护对话可读性

Monitor 内置速率限制，高输出事件流会被自动停止，防止对话被淹没。同时，200ms 内的连续 stdout 行会合并为一条通知，保持多行事件（如 Traceback）的整体性。这些机制要求 Claude 编写更精确的过滤器，并理解批处理行为，从而在监控效率和对话可读性之间取得平衡。

❓

Q&A

Claude Code 中的 Monitor 工具是做什么的？

Monitor 是 Claude Code 内置的事件流监听工具，用于持续监听外部事件流（如日志文件、WebSocket 流），每当有新事件（如日志中的一行）出现时，Claude 会收到通知。它适用于需要等待不确定时间点发生的事件，比如日志中出现错误、文件被修改等。

Monitor 与 Cron 和 Bash 后台任务有什么区别？

Monitor 是事件驱动的，外部事件发生才触发；Cron 是时间驱动的，到点就触发；Bash 后台任务只通知一次任务完成。Monitor 适合持续监听事件流，Cron 适合定时任务，Bash 后台适合等待单个任务完成。

Monitor 支持哪两种数据源？

Monitor 支持两种数据源：Shell 命令（command）和 WebSocket（ws）。Shell 命令的 stdout 每一行作为一个事件；WebSocket 的每个文本帧作为一个事件。两者互斥，只能选其一。

使用 Monitor 时，如何避免漏掉错误或失败信号？

Monitor 的 persistent 参数有什么作用？

persistent 参数设为 true 时，Monitor 会忽略 timeout，一直监听直到会话结束或手动停止。这适用于长期监控场景，如 PR 状态、日志追踪等。默认是 false，以避免长期监听带来的风险。

为什么 Monitor 内置 WebSocket 支持而不是使用 websocat 命令？

内置 WebSocket 支持避免了额外进程、shell 转义和缓冲问题，使帧到事件的映射更规范。这减少了脆弱性，是设计者认为 Claude 会用于 agent-to-agent 通信、订阅式部署事件等场景。

Monitor 的 rate limiting 机制是什么？

如果 Monitor 产生过多事件（例如每秒 100 行），系统会自动停止该 Monitor，以防止对话被淹没。Claude 会收到通知，需要重写更严格的过滤器后重新启动。

Monitor 的 200ms 批处理机制有什么作用？

200ms 内的连续 stdout 行会被合并成一个通知，这样多行输出（如 Python Traceback）可以作为一个整体呈现，避免对话被拆散。

🏷️