技能名称: openclaw-doctor
详细描述:

OpenClaw Doctor — macOS 网关看门狗 v2

针对 macOS 上 OpenClaw 网关的 24/7 健康监控程序。检测并自动修复四层故障。

为什么需要它

OpenClaw 网关是消息桥梁——如果它宕机，AI 助手将陷入沉默。macOS 上常见的故障模式：

| 层级 | 故障 | 症状 |
|------|------|------|
| L1 | 进程崩溃 | 完全静默 |
| L2 | HTTP 端口卡死 | 完全静默 |
| L3 | WebSocket 1006 断开 | 进程存活，HTTP 正常，但消息无法送达（最隐蔽！） |
| L4 | Mac 睡眠/休眠 | 合盖或空闲超时后所有连接中断 |

架构

LaunchAgent（每 5 分钟）
→ L1: pgrep + launchctl（进程存活？）
→ L2: curl HTTP 探测（端口响应？）
→ L3: 日志扫描 WS 1006 错误（通信健康？）
→ L4: caffeinate 保活（防止睡眠）
→ 遵循最小干预原则的自动修复

修复策略（逐步升级）

| 故障 | 操作 | 理由 |
|------|------|------|
| 进程崩溃 | openclaw doctor --repair → 重启网关 | 进程崩溃 |
| HTTP 不可达 | 重启网关 | 端口卡死 |
| WS 频繁断开 | 先重启 Node → 然后完全重启 | WS 层问题，通常重启 Node 即可 |
| 睡眠后恢复 | 网关 + Node 双重重启 | 所有连接需要重建 |

设置

1. 复制脚本

bash
cp scripts/doctor.sh ~/.openclaw/doctor.sh
chmod +x ~/.openclaw/doctor.sh

2. 配置（可选）

用于自定义的环境变量：

bash

在 ~/.bashrc 或 ~/.zshrc 中（若非默认值）

3. 安装 LaunchAgent

编辑 references/ai.openclaw.doctor.plist — 将 REPLACEWITHHOME 替换为你的实际主目录路径（例如 /Users/你的用户名）。

bash

复制并自定义 plist

加载服务

4. 验证

bash

手动测试运行

检查日志

确认 caffeinate 正在运行

确认 LaunchAgent 已加载

日志

位置：~/.openclaw/logs/doctor.log

| 前缀 | 含义 |
|------|------|
| HEARTBEAT | 定期健康确认（每小时） |
| ALERT | 检测到异常 |
| DIAGNOSIS | 故障分类 |
| ACTION | 修复进行中 |
| RESOLVED | 故障已修复 |
| CRITICAL | 所有修复尝试均失败 |
| INFO | 一般信息（例如 caffeinate 已启动） |

日志在 5MB 时自动轮转（保留最后 1000 行）。

故障排除

进程存活 + HTTP 正常但消息无法送达？
→ WS 断开。检查：grep 1006 /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log | tail -10

每晚断开连接？
→ Mac 睡眠。验证 caffeinate：pgrep -la caffeinate

Doctor 本身未运行？
→ 检查 LaunchAgent：launchctl list | grep doctor。如果缺失则重新加载。

临时禁用：
bash
launchctl bootout gui/$(id -u)/ai.openclaw.doctor

文件

• - scripts/doctor.sh — 主看门狗脚本
• references/ai.openclaw.doctor.plist — LaunchAgent 模板

版本历史

| 版本 | 日期 | 变更 |
|------|------|------|
| v1 | 2026-03-07 | 初始版本：进程检查 + HTTP 探测 + 网关重启 |
| v2 | 2026-03-23 | WS 健康检查 + Mac 睡眠预防 + 分层修复 + Node 重启 |