OpenClaw Guardian - 自愈守护进程

版本： 1.0.0
创建时间： 2026-03-07

🛡️ 功能概述

OpenClaw Guardian 是一个自动化的系统守护进程，用于保护 OpenClaw 系统的稳定运行。

核心功能

| 功能 | 说明 | |------|------| | 配置监控 | 实时监控配置文件变化，每分钟检查一次 | | 自动备份 | 修改前自动备份，保留最近 10 个版本 | | 故障检测 | 检测 JSON 损坏、文件丢失等问题 | | 自动恢复 | 从备份自动恢复损坏的配置 | | 定期体检 | 每小时全面健康检查 | | 日志轮转 | 自动清理 7 天前的旧日志 | | 进程守护 | Gateway 崩溃时自动重启 |

📦 安装

Guardian 已预装在 ~/.openclaw/guardian/ 目录。

🚀 使用

安全编辑配置（推荐）

使用安全编辑器修改配置，自动预检查和备份：

# 验证配置文件
node ~/.openclaw/guardian/safe-editor.js validate models.json

# 自动修复配置文件
node ~/.open/.guardian/safe-editor.js fix openclaw.json

# 手动备份
node ~/.openclaw/guardian/safe-editor.js backup channels.json

在代码中使用：

const { SafeConfigEditor } = require('./guardian/safe-editor.js');

const editor = new SafeConfigEditor('models.json');

// 方式 1：编辑 JSON 对象
editor.edit(data => {
  data.models.push({ name: 'new-model', endpoint: '...' });
  return data;  // 返回修改后的数据
});

// 方式 2：编辑原始文本
editor.editRaw(content => {
  // 自定义文本处理
  return content.replace(/old-value/g, 'new-value');
});

启动守护进程

# 方式 1：使用启动脚本
~/.openclaw/guardian/start.sh start

# 方式 2：直接运行 Node
cd ~/.openclaw/guardian
node guardian.js start

查看状态

# 查看运行状态
~/.openclaw/guardian/start.sh status

# 运行健康检查
node ~/.openclaw/guardian/guardian.js check

手动备份

node ~/.openclaw/guardian/guardian.js backup

查看日志

# 查看最近 50 行日志
node ~/.openclaw/guardian/guardian.js logs

# 或直接查看日志文件
tail -f ~/.openclaw/guardian/logs/guardian.log

停止守护进程

~/.openclaw/guardian/start.sh stop

📋 配置文件

配置文件位于 ~/.openclaw/guardian/config.json

{
  "checkInterval": 60000,        // 配置检查间隔（毫秒）
  "healthInterval": 3600000,     // 健康检查间隔（毫秒）
  "logRotateDays": 7,            // 日志保留天数
  "maxBackups": 10,              // 最大备份数量
  "criticalFiles": [             // 关键监控文件
    "openclaw.json",
    "models.json",
    "channels.json"
  ],
  "autoFix": {
    "enabled": true,             // 启用自动修复
    "methods": ["direct_fix", "backup_restore", "default_create"]
  }
}

🔧 自动修复策略

当检测到配置损坏时，Guardian 会按以下顺序尝试修复：

1. 直接修复

尝试修复常见 JSON 错误：

• 移除末尾多余逗号
• 补全缺失的闭合括号

2. 备份恢复

从最近的备份恢复配置文件

3. 创建默认配置

如果无备份可用，创建默认配置模板

📊 健康检查项目

| 检查项 | 说明 | |--------|------| | 配置文件 | 验证所有关键 JSON 文件有效性 | | 磁盘空间 | 检查磁盘使用率（>90% 报警） | | 进程状态 | 检查 Gateway 进程是否运行 | | 日志文件 | 检查日志文件大小（>100MB 警告） | | 备份状态 | 检查备份文件是否存在 |

📁 目录结构

~/.openclaw/guardian/
├── guardian.js          # 主程序
├── start.sh             # 启动脚本
├── config.json          # 配置文件
├── README.md            # 本文档
├── backups/             # 配置备份目录
│   └── *.bak           # 备份文件
└── logs/               # 日志目录
    ├── guardian.log    # 守护进程日志
    └── guardian.out.log # 输出日志

🔔 告警与通知

Guardian 会在以下情况发出告警：

• 配置文件损坏且无法自动修复
• 磁盘空间不足
• Gateway 进程崩溃且达到最大重启次数
• 健康检查发现严重问题

🐛 故障排查

Guardian 无法启动

# 检查 Node.js 版本
node --version  # 需要 >= 14.0.0

# 检查文件权限
ls -la ~/.openclaw/guardian/

# 查看详细错误
node ~/.openclaw/guardian/guardian.js help

配置无法恢复

# 查看可用备份
ls -la ~/.openclaw/guardian/backups/

# 手动恢复
cp ~/.openclaw/guardian/backups/openclaw.json.*.bak ~/.openclaw/openclaw.json

日志文件过大

# 手动清理日志
rm ~/.openclaw/guardian/logs/*.log

# 重启 Guardian
~/.openclaw/guardian/start.sh restart

📈 性能影响

• CPU 使用： < 1%（空闲时）
• 内存使用： ~50MB
• 磁盘空间： 备份文件约 1-5MB/个

🔐 安全说明

• 备份文件仅保存在本地
• 日志不包含敏感信息
• 建议定期导出重要备份到外部存储

📞 技术支持

如遇问题，请查看：

1. 日志文件：~/.openclaw/guardian/logs/guardian.log
2. 健康报告：node ~/.openclaw/guardian/guardian.js check

最后更新： 2026-03-07