ClawHub

qclaw-watchdog

Communication

QClaw Watchdog - Monitors and auto-restarts QClaw when issues are detected. Works independently of QClaw, communicates via Feishu for alerts and commands. QClaw 看门狗 - 监控并自动重启 QClaw，独立于 QClaw 运行，通过飞书发送告警和接收指令。

Install

openclaw skills install @kf-liu/qclaw-watchdog

QClaw Watchdog / QClaw 看门狗

功能 Features

  • 自动监控 - 可配置间隔检查 QClaw 状态
  • 自动修复 - 检测到异常时自动重启
  • 飞书通知 - 通过飞书发送状态通知
  • 远程控制 - 支持通过飞书发送指令
  • 配置分离 - 配置文件与代码分离
  • 自动更新 - 支持一键更新到最新版本

支持的指令 Commands

指令 Command说明 Description
状态 / status检查 QClaw 状态
重启 / restart重启 QClaw
启动 / start启动 QClaw
退出 / quit退出 QClaw
配置 / config显示当前配置
帮助 / help显示帮助

配置 Configuration

配置文件 (config.json)

{
  "feishu": {
    "app_id": "your-app-id",
    "app_secret": "your-secret",
    "user_id": "your-open-id"
  },
  "qclaw": {
    "health_url": "http://127.0.0.1:28789/health"
  },
  "watchdog": {
    "check_interval_ms": 180000,
    "restart_delay_ms": 10000,
    "max_retries": 3
  },
  "logs": {
    "main_log": "./watchdog.log",
    "command_log": "./commands.log"
  }
}

配置项说明

配置项默认值说明
check_interval_ms180000巡检间隔（毫秒），默认3分钟
restart_delay_ms10000重启延迟（毫秒），默认10秒
max_retries3最大重试次数

环境变量

也可以通过环境变量覆盖配置：

export FEISHU_APP_ID="your-app-id"
export FEISHU_APP_SECRET="your-secret"
export FEISHU_USER_ID="your-open-id"
export CHECK_INTERVAL_MS=300000

安装 Installation

1. 创建配置文件

./init-config.sh

编辑 config.json，填入你的飞书应用配置。

2. 启动看门狗

# 前台运行
./start.sh

# 后台运行
nohup ./start.sh >> watchdog.log 2>&1 &

3. 开机自启 (macOS)

# 编辑 plist，修改路径
vim com.user.qclaw-watchdog.plist

# 复制到 LaunchAgents
cp com.user.qclaw-watchdog.plist ~/Library/LaunchAgents/
launchctl load ~/Library/LaunchAgents/com.user.qclaw-watchdog.plist

更新 Update

自动更新

# 检查更新
./update.sh --check

# 从 GitHub 更新
./update.sh --github username/qclaw-watchdog

# 一键更新
./update.sh

# 强制更新
./update.sh --force

手动更新

# 备份配置
cp config.json config.json.bak

# 拉取最新代码
git pull

# 恢复配置
cp config.json.bak config.json

# 重启服务

发布 Publish

发布到 GitHub

# 安装 GitHub CLI (如果未安装)
brew install gh

# 登录 GitHub
gh auth login

# 发布
./publish.sh --github yourname/qclaw-watchdog

发布后，其他用户可以通过以下方式安装：

# 克隆仓库
git clone https://github.com/yourname/qclaw-watchdog.git

# 配置
./init-config.sh

# 启动
./start.sh

文件结构

qclaw-watchdog/
├── SKILL.md           # 说明文档
├── watchdog.js        # 主程序
├── config.json        # 配置文件（可选）
├── start.sh          # 启动脚本
├── update.sh         # 更新脚本
└── init-config.sh    # 配置初始化脚本

工作原理

┌─────────────┐     WebSocket      ┌─────────────┐
│  飞书服务器  │ ←──────────────→  │   看门狗    │
└─────────────┘                   └──────┬───────┘
                                         │
                          HTTP           ↓
                          GET         ┌─────────────┐
                                  │  QClaw      │
                                  │  Gateway    │
                                  └─────────────┘
  1. WebSocket 连接 - 看门狗通过 WebSocket 接收飞书消息
  2. 状态检查 - 定期检查 QClaw Gateway 健康状态
  3. 自动修复 - 异常时自动重启 QClaw
  4. 消息通知 - 通过飞书发送状态通知

飞书应用配置

1. 创建飞书企业自建应用

  1. 打开 飞书开发者后台
  2. 创建企业自建应用
  3. 添加权限：
    • im:message:send_as_bot - 发送消息
    • im:message:receive - 接收消息
  4. 启用事件订阅（长连接模式）
  5. 发布应用

2. 获取配置信息

配置项获取方式
App ID应用详情 → 凭证与基础信息
App Secret应用详情 → 凭证与基础信息
User Open ID见下文

3. 获取用户 Open ID

打开飞书 API 调试页面：

https://open.feishu.cn/api-explorer/cli_a9333bca0c78dceb?apiName=create&project=im&resource=message&version=v1
  1. 在页面中找到「发送消息 API」
  2. 查询参数 receive_id_type 选择 open_id
  3. 在请求体中输入用户的 open_id（可以用用户的飞书 ID 或手机号查询）
  4. 点击发送，即可看到返回的 open_id

注意事项

  • 确保 Node.js >= 18 已安装
  • 飞书应用需要已发布才能接收消息
  • 看门狗独立运行，QClaw 挂了也能监控和告警
  • 配置文件变更后需要重启生效
More in Communication