OpenClaw Guardian - 系统守护#

💡 跨平台支持：Linux + Windows 自动适配

功能概述#

• 定时自检：每日固定时间检查 OpenClaw Gateway 状态
• 异常检测：检测进程、WebSocket 连接、插件状态
• 自动自救：尝试自动恢复常见异常（重启服务、重新连接等）
• 自定义时间：用户可设置自检时间

自检项目#

0. Skills 状态检查#

• 检查目录是否存在
• 统计 skill 数量
• 对比基线检测丢失
• 检查每个 skill 是否有 SKILL.md

0.5 Channels 配置检查#

bash

cat ~/.openclaw/openclaw.json | grep -A 2 '"channels"'
ls ~/.openclaw/extensions/

• 检查配置文件中的 channels
• 统计已启用的 channels
• 检查 extensions 目录

1. Gateway 进程状态#

bash

openclaw gateway status

• 检查是否 running
• 检查 PID 是否存在

2. WebSocket 连接状态#

• 检查 Gateway 与各插件的连接
• 检测 1006 断开错误

3. 插件状态#

bash

openclaw status

4. 系统资源#

• CPU/内存使用率
• 磁盘空间

自救策略#

异常检测方式自救动作Gateway 未运行pgrep -f "openclaw-gateway" 无结果openclaw gateway start进程崩溃PID 不存在openclaw gateway restart端口占用端口检查失败释放端口或更换端口连接断开WebSocket 1006重启 Gateway

自救验证流程#

每次自救操作后必须验证是否成功：

bash

# 自救函数示例
try_recover() {
    local action="$1"
    echo "🔧 尝试自救: $action"

    # 执行自救动作
    eval "$action"

    # 等待服务启动
    sleep 5

    # 验证是否成功
    if pgrep -f "openclaw-gateway" > /dev/null; then
        echo "✅ 自救成功"
        return 0
    else
        echo "❌ 自救失败，需要手动处理"
        return 1
    fi
}

各自救动作的验证方法#

自救动作验证命令成功标志启动 Gatewaypgrep -f "openclaw-gateway"返回 PID重启 Gatewaypgrep -f "openclaw-gateway"返回 PID重连插件openclaw status插件状态正常

自救流程完整示例#

text

1. 检测异常: Gateway 进程不存在
2. 记录状态: 当前进程数=0
3. 尝试自救: openclaw gateway start
4. 等待 5 秒
5. 验证结果: pgrep -f "openclaw-gateway"
6. 成功? → 报告 ✅ 已恢复
   失败? → 报告 ❌ 需要手动处理

自救失败处理#

当自救失败时：

1. 不要重复尝试（避免死循环）
2. 明确报告异常情况
3. 提示用户手动处理
4. 记录详细日志供排查

使用方法#

Heartbeat 轻量检查（可选）#

在 HEARTBEAT.md 中添加轻量检查，每次 Heartbeat 轮询时快速检查：

text

## OpenClaw Guardian

- 检查 Gateway 进程是否存活: `pgrep -f "openclaw gateway"`
- 如果进程不在，尝试启动: `openclaw gateway start`
- 如果之前正常，这次突然挂了，报告异常

检查频率：每 1-2 个 Heartbeat 周期做一次（避免太频繁）

Cron 完整自检#

告诉用户使用 openclaw cron 设置定时任务：

bash

# 添加每日自检（早上 9 点）
openclaw cron add --name "guardian-daily" --schedule "0 9 * * *" --command "openclaw guardian check"

手动触发自检#

用户可以说：

• "运行自检"
• "检查系统状态"
• "帮我看看 Gateway 还好吗"

自检时自动配置外部守护#

首次运行自检时，自动检测操作系统并配置对应守护：

1. 检测当前系统： $OSTYPE 或 [Environment]::OSVersion
2. Linux → 检查 crontab 是否有守护 → 没有则添加
3. Windows → 检查任务计划程序是否有守护 → 没有则提示用户配置
4. 报告配置结果

bash

# 自动配置脚本
# 注意：以下路径假设 OpenClaw 安装在 ~/.openclaw 目录下
# 如果你的安装路径不同，请修改对应的路径
OPENCLAW_PATH=~/.openclaw
if ! crontab -l 2>/dev/null | grep -q "openclaw-gateway"; then
    (crontab -l 2>/dev/null; echo "*/5 * * * * pgrep -f \"openclaw-gateway\" > /dev/null || cd $OPENCLAW_PATH && node ./dist/daemon-cli.js start >> /tmp/gateway_guardian.log 2>&1") | crontab -
    echo "✅ 已自动配置外部守护（每 5 分钟检查）"
else
    echo "✅ 外部守护已配置"
fi

自救操作#

当检测到异常时：

1. 先尝试自动恢复
2. 记录操作日志
3. 报告恢复结果
4. 必须验证自救是否成功（见上文"自救验证流程"）

输出格式#

自检完成后，报告格式：

text

🛡️ OpenClaw 自检报告
时间: YYYY-MM-DD HH:mm
----------------
✅ Gateway: 运行中 (PID: xxx)
✅ 内存: 45%
✅ 磁盘: 60%
----------------
自检完成，无异常

或：

text

🛡️ OpenClaw 自检报告
时间: YYYY-MM-DD HH:mm
----------------
❌ Gateway: 已停止
🔧 尝试自救: 重启 Gateway...
✅ 自救成功！
----------------
状态: 已恢复

注意事项#

• 自救前记录当前状态
• 自救失败时提示用户手动处理
• 避免频繁重启（间隔至少 30 秒）

外部守护配置（推荐）#

问题：如果 Gateway 完全挂了，Agent 本身无法工作，需要外部守护。

解决方案：根据操作系统自动选择对应方案

自动检测操作系统#

首次自检时，自动检测并配置对应平台的守护：

bash

# 检测操作系统
if [[ "$OSTYPE" == "linux-gnu"* ]]; then
    echo "🟢 Linux 系统，使用 Cron 守护"
elif [[ "$OSTYPE" == "cygwin" ]] || [[ "$OSTYPE" == "msys" ]] || [[ "$OSTYPE" == "win32" ]]; then
    echo "🪟 Windows 系统，使用任务计划程序"
else
    echo "⚠️ 未知系统"
fi

Linux → Cron 守护#

自动配置（首次使用）#

当用户运行自检时，自动检查并配置 cron 守护：

bash

# 检查是否已有守护
crontab -l | grep "openclaw-gateway"

# 如果没有，自动添加（路径需要根据实际安装位置修改）
# 假设 OpenClaw 安装在 ~/.openclaw
(crontab -l 2>/dev/null; echo '*/5 * * * * pgrep -f "openclaw-gateway" > /dev/null || cd ~/.openclaw && node ./dist/daemon-cli.js start >> /tmp/gateway_guardian.log 2>&1') | crontab -

守护逻辑#

text

系统 Cron（独立于 Gateway）
    ↓ 每 5 分钟
pgrep 检查 Gateway 进程
    ↓ 如果不存在
执行启动命令

优势#

• 不需要 sudo 权限
• 不依赖 Agent 本身
• 系统级守护，Gateway 挂了也能救

手动配置（可选）#

如果需要修改检查间隔：

bash

crontab -e

# 每 3 分钟检查一次
*/3 * * * * pgrep -f "openclaw-gateway" > /dev/null || /path/to/start_gateway.sh

日志位置#

• 守护日志： /tmp/gateway_guardian.log

---

Windows → 任务计划程序 / PowerShell#

当检测到 Windows 系统时，使用以下方案：

方案 A: PowerShell 守护脚本

复制 scripts/guardian-windows.ps1 到用户目录并配置：

powershell

# 1. 修改脚本中的 Gateway 路径
# 2. 设置开机自启
$action = New-ScheduledTaskAction -Execute "powershell.exe" -Argument "-ExecutionPolicy Bypass -File C:\Users\你的用户名\.openclaw\scripts\guardian-windows.ps1"
$trigger = New-ScheduledTaskTrigger -At Startup
Register-ScheduledTask -TaskName "OpenClaw Guardian" -Trigger $trigger -Action $action -RunLevel Highest

方案 B: 定时检查（每 5 分钟）

powershell

$action = New-ScheduledTaskAction -Execute "powershell.exe" -Argument "-ExecutionPolicy Bypass -File C:\Users\你的用户名\.openclaw\scripts\guardian-windows.ps1"
$trigger = New-ScheduledTaskTrigger -Once -At (Get-Date) -RepetitionInterval (New-TimeSpan -Minutes 5) -RepetitionDuration (New-TimeSpan -Days 9999)
Register-ScheduledTask -TaskName "OpenClaw Guardian" -Trigger $trigger -Action $action -RunLevel Highest

自动配置逻辑

powershell

# 检测是否已有守护任务
$task = Get-ScheduledTask -TaskName "OpenClaw Guardian" -ErrorAction SilentlyContinue

if ($null -eq $task) {
    # 未配置，自动添加
    # ... 执行上面的注册命令
    Write-Host "✅ 已自动配置 Windows 守护（每 5 分钟检查）"
} else {
    Write-Host "✅ 守护已配置"
}

日志位置

• 守护日志： $env:USERPROFILE\.openclaw\logs\guardian.log

---

一键配置（首次使用）#

首次运行自检时自动检测操作系统并配置：

Linux#

bash

# 复制脚本到 ~/.openclaw/
mkdir -p ~/.openclaw
cp -r /path/to/openclaw-guardian/scripts/guardian-daily.sh ~/.openclaw/

# 添加 cron 任务（路径根据实际安装位置修改）
(crontab -l 2>/dev/null; echo '*/5 * * * * pgrep -f "openclaw-gateway" > /dev/null || cd ~/.openclaw && node ./dist/daemon-cli.js start >> /tmp/gateway_guardian.log 2>&1') | crontab -

# 添加每日报告任务
(crontab -l 2>/dev/null; echo '0 9 * * * ~/.openclaw/guardian-daily.sh >> /tmp/daily_report.txt 2>&1') | crontab -

Windows#

powershell

# 复制脚本
Copy-Item -Path "C:\path\to\openclaw-guardian\scripts\guardian-windows.ps1" -Destination "$env:USERPROFILE\.openclaw\scripts\"

# 手动修改 Gateway 路径后配置定时任务
# （需要用户修改脚本中的 $GatewayPath 变量）

分享给小伙伴：

1. 把整个 openclaw-guardian 文件夹发给他
2. 他放到 ~/.openclaw/skills/ 下
3. 运行自检时会自动配置