Agent Defibrillator

核心用法

Agent Defibrillator 是一款专为 macOS 设计的 launchd 守护进程 watchdog 工具，核心功能是监控 AI Agent 网关服务的健康状态并在崩溃时自动恢复。安装后，它会以 10 分钟为周期执行健康检查，通过检测进程状态、响应能力和版本一致性来判断服务是否异常。

当检测到崩溃或僵死进程时，Defibrillator 会执行分级恢复策略：先进行最多 3 次带延迟的重试，若仍失败则触发完整重启，并启用 5 分钟冷却期防止重启风暴。用户可通过环境变量精细调整所有阈值，还可配置 Discord Webhook 实现故障实时推送。

显著优点

1. 原生 macOS 集成：深度利用 launchd 生态，无需 Docker 或第三方依赖，资源占用极低
2. 防御性设计：冷却期和重试机制有效避免「病急乱投医」式的过度重启
3. 透明可审计：Shell 脚本实现，代码可 Review，日志路径清晰，符合 Unix 哲学
4. 版本漂移检测：能识别升级后的版本不匹配问题，减少隐性故障

潜在局限

• 平台锁定：仅支持 macOS，Linux 用户需自行适配 systemd
• 单点风险：watchdog 本身若被意外终止，监控能力即丧失（建议配合系统级监控）
• 网络盲区：健康检查逻辑未明确说明是否覆盖网络连通性检测，可能漏检「假死」状态
• 通知渠道单一：仅内置 Discord，企业环境常见的 PagerDuty/Slack/飞书需二次开发

适合人群

• 个人开发者或小团队运行 OpenClaw 等 AI Agent 网关
• 需要 7×24 小时稳定服务但无专职运维的 macOS 用户
• 偏好轻量级 Shell 方案、排斥 Kubernetes 复杂度的场景

常规风险

| 风险类型 | 说明 |

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

| 权限风险 | install.sh 需要修改 ~/Library/LaunchAgents，需警惕供应链攻击 |

| 误重启风险 | 配置不当可能导致正常服务被频繁中断，建议充分测试 DEFIB_MAX_RETRIES 阈值 |

| 日志累积 | 长期运行需配置 logrotate 防止磁盘占满 |

| 通知疲劳 | Discord 高频告警可能导致重要信息被淹没 |

核心功能

Agent Defibrillator 是一款专为 macOS 设计的轻量级看门狗（watchdog）服务，通过 launchd 持续监控 AI Agent Gateway 进程健康状态。其核心职责包括：每 10 分钟执行一次健康检查；检测进程崩溃、僵死状态及版本不匹配；触发自动重启时启用冷却保护（默认 300 秒）防止重启风暴；可选配置 Discord 通知推送。

显著优点

• 系统级集成：深度利用 macOS launchd 服务框架，开机自启、崩溃恢复等机制原生支持
• 防御性设计：冷却保护、最大重试次数限制、锁文件防并发等多重机制避免故障级联
• 零依赖部署：纯 Shell/Bash 实现，无需第三方运行时或库，依赖审计得分 95
• 可观测性：完整的日志轮转与结构化输出，支持手动触发检查与实时日志追踪
• 配置灵活：环境变量驱动配置，支持自定义检查间隔、重试策略及通知渠道

潜在局限与风险

| 风险点 | 说明 |

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

| **远程代码下载（L1）** | install.sh 通过 curl 从 GitHub Raw 拉取脚本，缺少 SHA256 校验或签名验证，存在供应链攻击面 |

| **来源可信度 T2** | 维护者 hazy2go 为个人开发者账号，社区项目级别，需用户自行评估信任 |

| **本地明文通信** | 健康检查使用 HTTP 而非 HTTPS（localhost:18789），虽无外泄风险但可被本地其他进程嗅探 |

| **SIGKILL 强制终止** | 清理孤儿进程时使用 `kill -9`，若匹配模式不精确存在误杀风险 |

| **平台锁定** | 仅限 macOS，Linux/Windows 用户无法使用 |

适合人群

• 运行 OpenClaw 等 AI Agent Gateway 的 macOS 开发者或高级用户
• 需要无人值守运行、对服务可用性有要求的自动化场景
• 具备基础 Shell 脚本阅读能力，愿意审查代码后再执行安装的用户

使用建议

1. 安装前必读：通过 git clone 替代 curl | bash 方式，人工审查 defibrillator.sh 内容
2. 验证校验和：关注仓库是否后续添加 SHA256 校验机制，或自行计算比对
3. 最小权限：检查 launchd plist 配置，确保仅申请必要权限
4. 监控日志：定期审查 ~/.openclaw/logs/defibrillator.log 观察异常重启模式

安全评级说明

综合评分 68（Grade B），属于"基础级可用"——功能完整、设计合理，但存在可改进的供应链安全环节。建议在生产环境关键路径中增加额外的完整性验证层。