Openclaw Rescue Kit

OpenClaw 自救套件 - 网关启动包装（端口冲突防护）、看门狗监控、自动重启、配置回滚、安全加固、日志清理、Git版本管理。当用户提到 OpenClaw 网关崩溃、需要看门狗、配置回滚、安全扫描、日志清理、端口冲突、或部署自救脚本时使用此技能。包含 10 个独立脚本和完整部署指南。

OpenClaw 自救套件

一套完整的 Shell 脚本，用于保障 OpenClaw AI 助手 7x24 小时稳定运行。

快速安装

从 clawhub 安装（推荐）

clawhub install openclaw-rescue-kit
bash ~/.openclaw/skills/openclaw-rescue-kit/scripts/install-rescue-kit.sh

从 .skill 文件安装

clawhub install ./openclaw-rescue-kit.skill
bash ~/.openclaw/skills/openclaw-rescue-kit/scripts/install-rescue-kit.sh

手动安装

mkdir -p ~/.openclaw/scripts ~/.openclaw/logs ~/.openclaw/backups
cp ~/.openclaw/skills/openclaw-rescue-kit/scripts/*.sh ~/.openclaw/scripts/
chmod +x ~/.openclaw/scripts/*.sh
bash ~/.openclaw/scripts/install-rescue-kit.sh

安装完成后：

# 1. 编辑告警配置（填入飞书/Telegram Webhook）
vim ~/.openclaw/notify.conf

# 2. 保存安全配置
bash ~/.openclaw/scripts/security-hardening.sh --save-safe

# 3. 保存 Git 安全版本
bash ~/.openclaw/scripts/git-tag.sh save-safe

# 4. 测试告警
bash ~/.openclaw/scripts/notify.sh -l INFO "自救套件部署完成"

脚本清单

脚本	功能	运行方式
core.sh	核心诊断（网关状态、配置验证）	被其他脚本调用
gateway-start.sh	网关启动包装（端口冲突防护 + 自动清理）	被 LaunchAgent 调用
gateway-watchdog.sh	网关看门狗（配置验证+自动回滚+重启）	定时任务
health-check.sh	健康检查（资源、消息活动）	定时任务
git-tag.sh	配置快照与回滚（Git tag）	手动/看门狗触发
security-hardening.sh	安全加固扫描	手动
notify.sh	告警通知（飞书/Telegram/企微/钉钉）	被其他脚本调用
log-cleaner.sh	智能日志清理	定时任务

| safe-config-modify.sh | 安全配置修改（原子写入+自动回滚） | 手动/被其他脚本调用 |

git-tag.sh 使用（配置回滚）

# 查看所有配置快照
bash ~/.openclaw/scripts/git-tag.sh list

# 快速回滚到上一个安全版本
bash ~/.openclaw/scripts/git-tag.sh quick-rollback

# 回滚到指定版本
bash ~/.openclaw/scripts/git-tag.sh rollback <tag-name>

定时任务配置

macOS LaunchAgent（推荐）

macOS 上 crontab 受 SIP 限制，推荐使用 LaunchAgent。

安装脚本会自动生成 plist 到 ~/.openclaw/launchagents-ready/（路径已正确替换）。

如果安装脚本因沙箱权限无法自动复制，请手动执行：

# 复制已准备好的 plist（路径已替换，无需手动修改）
cp ~/.openclaw/launchagents-ready/*.plist ~/Library/LaunchAgents/

# 加载所有服务
launchctl load ~/Library/LaunchAgents/ai.openclaw.watchdog.plist
launchctl load ~/Library/LaunchAgents/ai.openclaw.healthcheck.plist
launchctl load ~/Library/LaunchAgents/ai.openclaw.logcleaner.plist
launchctl load ~/Library/LaunchAgents/ai.openclaw.gittag.plist

# 验证
launchctl list | grep openclaw

服务说明：

服务	频率	功能
ai.openclaw.gateway	持续 (KeepAlive)	网关进程守护（OpenClaw 自带）
ai.openclaw.watchdog	每分钟	配置验证 + 自动回滚 + 重启
ai.openclaw.healthcheck	每小时	健康检查 + 告警
ai.openclaw.logcleaner	每天	日志清理 + Session 瘦身
ai.openclaw.gittag	每天	Git 配置基线版本

管理命令：

# 停止服务
launchctl unload ~/Library/LaunchAgents/ai.openclaw.watchdog.plist

# 重启服务
launchctl unload ~/Library/LaunchAgents/ai.openclaw.watchdog.plist
launchctl load ~/Library/LaunchAgents/ai.openclaw.watchdog.plist

# 查看日志
tail -f ~/.openclaw/logs/watchdog.log

Linux crontab

Linux 上可以使用 crontab：

crontab -e

添加以下内容：

# OpenClaw 自救套件定时任务
SHELL=/bin/bash
PATH=/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin

# 每分钟检查网关（看门狗）
* * * * * /bin/bash $HOME/.openclaw/scripts/gateway-watchdog.sh >> $HOME/.openclaw/logs/cron.log 2>&1

# 每小时健康检查
0 * * * * /bin/bash $HOME/.openclaw/scripts/health-check.sh >> $HOME/.openclaw/logs/cron.log 2>&1

# 每天凌晨3点日志清理
0 3 * * * /bin/bash $HOME/.openclaw/scripts/log-cleaner.sh >> $HOME/.openclaw/logs/cron.log 2>&1

# 每天凌晨2:30 Git 基线版本
30 2 * * * /bin/bash $HOME/.openclaw/scripts/git-tag.sh save-baseline >> $HOME/.openclaw/logs/cron.log 2>&1

安全配置修改

使用 safe-config-modify.sh 进行配置修改，自动处理通知、备份、验证、回滚：

# 安全修改配置
bash ~/.openclaw/scripts/safe-config-modify.sh modify "操作名" "描述" '修改命令'

# 查看当前操作状态
bash ~/.openclaw/scripts/safe-config-modify.sh state

# 重启后恢复检查（watchdog 自动调用）
bash ~/.openclaw/scripts/safe-config-modify.sh recovery

安全流程：

1. 先发送通知给用户
2. Git 快照备份
3. 记录操作状态（用于重启后恢复）
4. 原子写入配置（先写临时文件，验证 JSON 后替换）
5. 验证配置合法性
6. 重启网关
7. 验证网关运行
8. 失败则自动回滚

配置修改公约（必须遵守）

修改 openclaw.json 前必须按以下流程操作：

1. 备份    → bash ~/.openclaw/scripts/git-tag.sh save-working
2. 检查    → bash ~/.openclaw/scripts/core.sh（确认网关正常）
3. 修改    → 编辑配置文件
4. 验证    → openclaw gateway status
5. 成功    → bash ~/.openclaw/scripts/git-tag.sh save-safe
6. 失败    → bash ~/.openclaw/scripts/git-tag.sh quick-rollback

获取飞书 Webhook

1. 在飞书群聊中，点击右上角「设置」→「群机器人」→「添加机器人」→「自定义机器人」
2. 输入机器人名称（如：OpenClaw 告警）
3. 复制生成的 Webhook URL
4. 填入 ~/.openclaw/notify.conf

告警通知配置

编辑 ~/.openclaw/notify.conf，填入至少一个 Webhook：

# 飞书机器人 Webhook
FEISHU_WEBHOOK_URL="https://open.feishu.cn/open-apis/bot/v2/hook/YOUR_HOOK_ID"

# Telegram（可选）
# TELEGRAM_BOT_TOKEN="your_bot_token"
# TELEGRAM_CHAT_ID="your_chat_id"

# 企业微信（可选）
# WECHAT_WEBHOOK_URL="your_webhook_url"

# 钉钉（可选）
# DINGTALK_WEBHOOK_URL="your_webhook_url"

关键经验

• 端口冲突导致重启失败 → gateway-start.sh 启动前自动清理端口占用和锁文件
• 网关挂了 AI 诊断不了自己 → 使用独立脚本 + 端口检测
• Webhook 通知不依赖网关 → 网关挂了也能发告警
• macOS 上 LaunchAgent 比 crontab 更可靠
• KeepAlive 只管重启，不管配置验证 → 看门狗脚本仍有价值
• 必须有锁文件机制 → 防止看门狗重复执行
• 必须有重启冷却期 → 避免频繁重启（默认 60 秒）
• 必须有重启次数限制 → 防止无限循环（默认 3 次）

故障排查

# 网关反复重启
tail -f ~/.openclaw/logs/watchdog.log
bash ~/.openclaw/scripts/core.sh
bash ~/.openclaw/scripts/git-tag.sh list

# 告警不生效
bash ~/.openclaw/scripts/notify.sh "测试消息"
cat ~/.openclaw/logs/unsent_alerts.log

# 配置回滚失败
ls -la ~/.openclaw/backups/
bash ~/.openclaw/scripts/git-tag.sh list

详细文档

完整使用说明和踩坑记录见 references/guide.md