name: openclaw-health-guardian description: 部署 OpenClaw 健康监控服务，支持自动重启、冷却期（180 秒）及速率限制（5 次/小时）。适用场景：（1）配置 OpenClaw 健康检查；（2）自动重启异常的 Gateway；（3）持续监控 OpenClaw 运行状态；（4）在 macOS 上部署健康守护进程。

metadata: { "openclaw": { "emoji": "🛠️", "requires": { "bins": ["node"] } },

}

OpenClaw Health Guardian

通过智能速率限制，自动监控并恢复 OpenClaw Gateway。

快速开始

安装健康守护进程：

bash ~/.openclaw/skills/openclaw-health-guardian/scripts/install.sh

验证安装结果：

launchctl list | grep openclaw

适用场景

• Gateway 频繁无响应
• 需要无需人工干预的自动恢复能力
• 在支持 LaunchAgent 的 macOS 系统上运行 OpenClaw
• 需防止重启循环，启用冷却保护机制

功能特性

工作流程

1. 安装守护进程

   bash ~/.openclaw/skills/openclaw-health-guardian/scripts/install.sh
   

2. 验证服务是否运行

   launchctl list | grep com.openclaw.healthcheck
   

3. 实时查看日志

   tail -f ~/.openclaw/logs/health-check.log
   

4. 手动测试（可选）

   bash ~/.openclaw/scripts/openclaw-health-check.sh
   

常用命令

文件结构

安装完成后目录结构如下：

~/.openclaw/
├── scripts/
│   └── openclaw-health-check.sh    # 主执行脚本
├── state/
│   ├── last_restart                # 上次重启时间戳
│   ├── restart_count               # 当前小时重启计数
│   └── hour_marker                 # 小时标记文件（用于重置计数）
└── logs/
    ├── health-check.log            # 主日志文件
    ├── health-check-daemon.log     # 守护进程 stdout 日志
    └── health-check-daemon-error.log # 守护进程 stderr 日志

~/Library/LaunchAgents/
└── com.openclaw.healthcheck.plist  # LaunchAgent 配置文件

日志示例

正常状态：

[2026-03-16 10:28:47] No issues found. OpenClaw is healthy!

触发冷却期：

[2026-03-16 10:30:05] 冷却期内 (120s/180s)，跳过重启操作

触发速率限制：

[2026-03-16 10:30:05] 本小时已达重启上限(5次)，跳过

成功执行重启：

[2026-03-16 10:30:02] 已记录重启事件 (冷却: 180s, 限流: 5/小时)
[2026-03-16 10:30:05] Gateway restart completed successfully

卸载方法

# 停止并移除服务
launchctl unload ~/Library/LaunchAgents/com.openclaw.healthcheck.plist
rm ~/Library/LaunchAgents/com.openclaw.healthcheck.plist

# 删除脚本与日志文件
rm ~/.openclaw/scripts/openclaw-health-check.sh
rm -rf ~/.openclaw/state/
rm ~/.openclaw/logs/health-check*.log

依赖要求

• macOS 10.14 及以上版本
• 已安装 OpenClaw
• 当前用户对主目录具备写入权限

参考资料

• references/technical-details.md — 实现细节说明
• references/troubleshooting.md — 常见问题排查指南