核心功能
BlueBubbles Healthcheck 是一个专门解决 iMessage 网关连接问题的诊断与自愈工具，针对 BlueBubbles 与 OpenClaw 之间的 webhook 连接故障设计。
核心用法
该技能采用「诊断-修复-验证」的三段式工作流：
- diagnose.sh（只读诊断）：执行4步检测——BlueBubbles 服务器可达性、webhook 注册状态、OpenClaw 端点响应性、近期 webhook 投递活动，返回结构化状态码
- heal.sh（自动修复）：根据诊断结果执行针对性修复——重启 OpenClaw 网关、删除 stale webhook 并重新注册、验证修复效果
- reset-webhook.sh（原子操作）：独立的 webhook 删除+重注册工具
支持 --dry-run 模式预览修复操作，环境变量与命令行参数双轨配置，便于脚本集成。
显著优点
1. 精准定位故障模式：覆盖4类典型故障（网关重启导致 webhook 丢失、BlueBubbles 退避状态、网关未运行、BB.app 未启动），并提供明确修复路径
2. 零停机自愈：大多数场景无需人工干预，脚本级自动修复
3. 可观测性设计：诊断结果以 ✅/❌ 直观呈现，exit code 标准化，易于集成到 HEARTBEAT.md 定期巡检
4. 原子化操作：webhook 重置为单文件脚本，降低操作风险
潜在局限
- 依赖外部凭证：需要
BB_PASSWORD明文或环境变量注入，存在凭证泄露风险 - Mac 端无法自动修复：BlueBubbles.app 未运行时仅能提示用户手动启动，无法远程恢复
- 网络层盲区：不处理 BlueBubbles 与 iMessage 服务之间的 Apple 服务器连接问题
- 修复策略偏激进：自动重启网关可能中断正在进行的消息处理
适用人群
- OpenClaw 网关运维者
- 自建 iMessage 桥接服务的用户
- 需要 7×24 小时 iMessage 可靠性的自动化场景
常规风险
| 风险类型 | 说明 |
|---------|------|
| 凭证暴露 | `BB_PASSWORD` 通过环境变量传递，可能在进程列表中泄露 |
| 误修复 | 网关重启可能丢失消息队列状态 |
| 依赖循环 | 若 OpenClaw 本身故障，heal.sh 的网关重启可能失败 |
| 网络误报 | 瞬时网络抖动可能触发不必要的修复操作 |
建议生产环境配合 HEARTBEAT.md 定期巡检，而非高频自动修复，避免 flapping。