infra-heartbeat#

OpenClaw 基础设施心跳守护进程，负责：

• Gateway 监控：WebSocket 连通性检测，DOWN 时自动重启（最多连续 3 次）
• 主机资源：磁盘 / 内存 / CPU / 进程监控，超阈值飞书告警
• 配置安全：变更前自动备份，JSON 损坏时自动回滚
• 进程保活：由 systemd 托管，崩溃自动重启，不依赖 nohup

快速开始#

首次安装#

bash

bash ~/.openclaw/extensions/infra-heartbeat/scripts/install-heartbeat.sh

交互式安装向导会要求填写必填配置（飞书 App ID/Secret、Gateway Token、通知目标）。

常用操作#

bash

# 查看状态
systemctl --user status heartbeat-daemon

# 查看日志
tail -f ~/.openclaw/workspace-infra/heartbeat.log

# 重启服务
systemctl --user restart heartbeat-daemon

# 卸载
bash ~/.openclaw/extensions/infra-heartbeat/scripts/uninstall-heartbeat.sh

配置#

配置文件： ~/.config/infra-heartbeat/config.env

详细配置参数见 references/configure.md。

关键参数速查#

参数必填默认值说明FEISHU_APP_ID✅—飞书应用 App IDFEISHU_APP_SECRET✅—飞书应用 App SecretGATEWAY_TOKEN✅—Gateway 访问令牌TARGET_OPEN_ID✅—通知目标 open_idCHECK_INTERVAL—180s检测间隔DISK_THRESHOLD—80%磁盘告警阈值MEM_THRESHOLD—85%内存告警阈值CPU_THRESHOLD—60%CPU 告警阈值

修改配置后生效#

bash

systemctl --user restart heartbeat-daemon

部署到新机器#

1. 将 infra-heartbeat/ skill 目录复制到新机器 ~/.openclaw/extensions/
2. 运行 bash install-heartbeat.sh
3. 填写新机器的 GATEWAY_TOKEN、 TARGET_OPEN_ID 等参数

无需修改脚本，配置全部外部化。

自动恢复逻辑#

text

锚点机制：
  - 每次检测到 Gateway UP → 若配置 MD5 有变化 → 保存 last-good.1/.2/.3（最多3份，轮转）
  - last-good.N 之间 MD5 均不同，确保每份都是真实变更过的配置

Gateway DOWN
  ├─ 连续失败 < 3 次
  │   ├─ 备份当前配置（仅供历史记录，不用于回滚）
  │   ├─ 校验 JSON → INVALID → rollback_one（仅回滚，不重启）
  │   ├─ restart → sleep 60 → check
  │   │   ├─ UP   → 成功，清零计数，下次 UP 时更新 last-good
  │   │   └─ DOWN → rollback_config() 依次尝试：
  │   │               last-good.1 → restart → check
  │   │               ↓ DOWN      last-good.2 → restart → check
  │   │               ↓ DOWN      last-good.3 → restart → check
  │   │               ↓ DOWN      → 失败计数+1，告警"需人工介入"
  │   └─ 连续 ≥ 3 次 → 停止自动重启
  │
  └─ 连续失败 ≥ 3 次 → 停止自动重启 → 发"需人工介入"通知

与 cron 健康检查的区别#

• Heartbeat Daemon：3 分钟间隔，发现故障自动恢复，systemd 进程保活
• Cron daily-health-check：每天一次，纯告警，不自动恢复

两者互为补充，生产环境建议同时运行。

获取当前配置参考值#

bash

# Gateway Token
cat ~/.openclaw/openclaw.json | jq -r '.gateway.auth.secret'

# 查看当前运行的配置
systemctl --user show heartbeat-daemon --property=ExecStart