qclaw-watchdog

QClaw Watchdog - Monitors and auto-restarts QClaw when issues are detected. Works independently of QClaw, communicates via Feishu for alerts and commands. QC...

Security Scan

The skill's code broadly matches a QClaw watchdog (checks a local health URL, restarts the app, and uses Feishu), but there are multiple inconsistencies (embedded Feishu credentials in the shipped config, undocumented env requirements, macOS-only commands while the registry lists no OS restriction, and missing referenced update/publish scripts) that make the package suspicious and worth further review before installing.

Purpose & Capability

The code implements a monitor that polls a local QClaw health URL, uses system commands to detect and restart QClaw, and communicates via Feishu — which aligns with the stated watchdog purpose. However, the skill manifests no declared required env vars or OS restriction while the code is clearly macOS/Unix-specific (uses open, osascript, pkill, pgrep) and expects Feishu credentials (either in config.json or environment). That mismatch between metadata and implementation is concerning.

Instruction Scope

SKILL.md instructs running init-config.sh and start.sh (expected) and references update.sh and publish.sh for updates/publishing, but those scripts are not present in the distributed file list. SKILL.md also suggests creating a LaunchAgents plist for macOS autostart. The runtime instructions expect editing/creating configuration containing Feishu credentials and potentially setting env vars (FEISHU_APP_ID/SECRET/USER_ID), but the package metadata declared no required env variables — an inconsistency. The instructions also instruct adding a NODE_PATH that points into a QClaw app installation, which assumes a specific host setup not documented in registry metadata.

Install Mechanism

There is no external installer or remote download — this is instruction-only with bundled scripts and code. That reduces supply-chain download risk. However, the package does not include dependency installation guidance (no npm install step or package.json provided), yet it requires the '@larksuiteoapi/node-sdk' module; start.sh relies on a NODE_PATH pointing into another app to satisfy dependencies, which is brittle and unusual.

Credentials

The repo ships a config.json containing Feishu app_id, app_secret, and a user_id (plaintext). The code also reads FEISHU_* env vars if set. The registry metadata declared no required credentials, but the skill clearly needs Feishu credentials to function; embedding what appear to be real credentials in the repo is a major red flag — either these are leaked/placeholder sensitive values or the package will operate using those credentials if left unchanged. Requesting QClaw control via local system commands is proportionate for a watchdog, but the undisclosed credential requirement and included secret are disproportionate and risky.

Persistence & Privilege

The skill does not request always:true and is user-invocable only. It suggests user actions to enable autostart (launchctl plist), which is a normal instruction for a watchdog service. It runs system commands to manage another application (open, osascript, pkill), which is expected for a restart-capable monitor but grants it the ability to control local processes — an expected but high-impact capability. Combine this with the embedded Feishu credentials and autonomous invocation could increase blast radius; be cautious.

What to consider before installing

Do not install or run this skill blindly. Key points to check before proceeding: - Treat the shipped config.json as sensitive: it contains a Feishu app_id and app_secret in plaintext. Assume those credentials are valid and compromised; rotate or remove them and replace with your own credentials stored securely (do not keep secrets in repo files). - The registry lists no required env vars or OS restriction, but the code requires FEISHU_* credentials and uses macOS-specific commands (open, osascript, pkill, pgrep). Only run on a controlled macOS host and only if you accept that the watchdog will be able to start/stop QClaw. - The SKILL.md references update.sh/publish.sh which are missing — ask the author for the missing files and verify the update mechanism before enabling automatic updates. - The package does not include dependency installation (no package.json shown). The code requires '@larksuiteoapi/node-sdk' — verify how that dependency will be provided (npm install or existing QClaw-provided node_modules). The start.sh attempts to point NODE_PATH into /Applications/QClaw.app — this is unusual and fragile. - Review the code paths that run shell commands (pgrep, open, pkill, osascript, child_process.exec) and ensure you run the watchdog with least privilege and that logs and command files are stored where you expect. - If you decide to test it, run in an isolated environment (non-production machine or VM), replace credentials with test values, and audit network traffic and the Feishu app to ensure no unexpected behavior. If you cannot verify the origin and author of this package, prefer not to run it with real credentials or on a production host.

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    │
                                  └─────────────┘

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 挂了也能监控和告警
• 配置文件变更后需要重启生效