- name
- qclaw-watchdog
- description
- |
- metadata
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_ms | 180000 | 巡检间隔（毫秒），默认3分钟 |
restart_delay_ms | 10000 | 重启延迟（毫秒），默认10秒 |
max_retries | 3 | 最大重试次数 |
环境变量
也可以通过环境变量覆盖配置：
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 │
└─────────────┘- WebSocket 连接 - 看门狗通过 WebSocket 接收飞书消息
- 状态检查 - 定期检查 QClaw Gateway 健康状态
- 自动修复 - 异常时自动重启 QClaw
- 消息通知 - 通过飞书发送状态通知
飞书应用配置
1. 创建飞书企业自建应用
- 打开 飞书开发者后台
- 创建企业自建应用
- 添加权限：
- im:message:send_as_bot - 发送消息 - im:message:receive - 接收消息
- 启用事件订阅（长连接模式）
- 发布应用
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- 在页面中找到「发送消息 API」
- 查询参数
receive_id_type选择open_id - 在请求体中输入用户的 open_id（可以用用户的飞书 ID 或手机号查询）
- 点击发送，即可看到返回的 open_id
注意事项
- 确保 Node.js >= 18 已安装
- 飞书应用需要已发布才能接收消息
- 看门狗独立运行，QClaw 挂了也能监控和告警
- 配置文件变更后需要重启生效