Openclaw Rescue Kit

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

Security Scan

脚本总体与“网关自救/看门狗/配置回滚”目的相符，但声明的依赖与运行时实际需要不一致，且脚本会修改用户启动项、强杀进程、读取/修改会话和配置文件并提交到本地 Git，存在明显的权限/敏感数据和持久化风险，建议在信任之前进行人工审查并在隔离环境中测试。

Purpose & Capability

技能名与描述（看门狗、端口清理、回滚等）与脚本实际功能基本一致 — 脚本会做端口清理、重启、配置验证、回滚、告警与日志清理。但 SKILL metadata 声称“Required binaries: none / Required env vars: none”，与脚本中大量对 openclaw、jq、curl、lsof、git、launchctl/systemctl、node/npm 等外部命令的依赖不符。声明与实际需求不匹配，可能让用户误以为安装无额外依赖。

Instruction Scope

运行说明要求复制并执行 install-rescue-kit.sh，会：拷贝脚本到 ~/.openclaw、初始化/修改用户 LaunchAgents 或 crontab、运行 PlistBuddy 修改 plist、强制 kill 占用端口的进程、init 本地 Git 仓库并提交配置、读取/解析会话文件和日志等。大部分行为在“自救套件”范畴内，但脚本会读取会话文件（可能包含敏感对话）、写入/删除日志与 session、并自动将配置提交到 Git，这些操作触及敏感数据与持久化变更，应在安装前得到明确授权与审查.

Install Mechanism

没有远程下载或不可信 URL，安装通过运行自带的 install-rescue-kit.sh 或手动复制脚本完成，未从外部服务器拉取并执行代码——这降低了远程代码注入风险。但 install 脚本会修改用户启动项（LaunchAgents / crontab）并尝试自动加载 plist，这属于高影响的本地修改，用户应手动审核将被写入的 plist 内容。

Credentials

metadata 未声明任何环境变量或凭据，但脚本使用并尊重多种 env/config（OPENCLAW_HOME, OPENCLAW_GATEWAY_PORT, OPENCLAW_LOG_DIR、notify.conf 中的 FEISHU/TELEGRAM 等令牌）。此外脚本会初始化 Git 并把配置文件提交到 ~/.openclaw 的仓库（若配置中含有令牌或凭据，会被纳入版本控制，尽管 .gitignore 尝试忽略某些目录）。声明中没有提示会访问/依赖这些环境变量与凭据，存在不透明性。

Persistence & Privilege

脚本会创建长期运行的守护任务（macOS LaunchAgent 条目或 Linux crontab），并在用户主目录下建立日志、备份和 Git 仓库，实现持续存在与自动运行。always:false（正常），但该持久化会在用户层面修改启动项和定时任务，安装前应知晓并同意这些修改。

What to consider before installing

要点与建议： - 主要不一致：技能声明不需要任何外部二进制或环境变量，但脚本实际会调用 openclaw、jq、curl、lsof、git、launchctl/systemctl、node/npm 等。不要以 “不需依赖” 为由盲目安装。 - 在安装前人工审查：逐行查看 install-rescue-kit.sh、gateway-start.sh、gateway-watchdog.sh、git-tag.sh 等脚本，确认要被修改的 LaunchAgent plist 内容、crontab 条目与写入路径。特别检查任何会读取或提交 ~/.openclaw/agents/main/sessions、~/.openclaw/openclaw.json、logs 目录的代码（这些可能包含敏感会话或凭据）。 - 敏感数据与 Git：脚本会 init 一个本地 Git 仓库并提交配置，若 openclaw.json 或其他文件包含令牌/凭据，会被提交并长期保留。请在安装前将敏感项移出或在 .gitignore 中显式忽略，或手动管理初始化/提交步骤。 - Webhook/通知令牌：notify.conf 为空模板，脚本只在用户填入后才会向这些 Webhook 发送告警。仅使用受信任的 Webhook URL，并限制其权限（群机器人的 Webhook 通常是合适的选择）。 - 测试与回滚：先在隔离环境或非生产的 OpenClaw 实例上运行安装与监控脚本，观察行为；确认 kill/cleanup 逻辑不会误杀其他关键进程。保留原始 plist 和配置备份（install 脚本会备份，但建议手动备份）。 - 依赖安装：确保系统安装了 jq、curl、lsof（可选但建议）与 git，或修改脚本以适配你的环境。 - 最小权限原则：以普通用户身份运行安装（脚本主要操作用户目录），不要用 root 运行；在 macOS 上对 plist 的修改可能需要你手动批准，谨慎执行自动加载步骤。 如果你希望我给出更精确的风险点，我可以： - 列出所有脚本中对外部命令/路径/网络的具体调用清单； - 标注会读取或写入可能包含敏感内容的具体文件路径； - 提供一个“安全化安装”步骤清单（如何先备份、如何手动审查并只启用部分功能）。

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