wzz-server-monitor

监控服务器 CPU/内存/磁盘使用率，超过配置阈值时通过 SMTP 发送邮件告警。支持可配置阈值、通知时间窗口、发送频率（防刷屏）和邮件文案模板。当用户询问服务器资源、负载、告警、监控通知、设置或查看资源监控时使用。Make sure to use whenever the user asks about server resource monitoring, load, or email alerts.

Clark Guz@xiuyiwzz

Install

openclaw skills install @xiuyiwzz/wzz-server-monitor

wzz-server-monitor — 服务器资源监控通知

监控 CPU / 内存 / 磁盘使用率，超过阈值时通过 SMTP 发送邮件告警。核心脚本由 cron 独立定时运行，与任何 AI Agent 无关；本 SKILL.md 是配置文档和交互入口。

1. 快速开始

新用户三步完成：

初始化（检查依赖、生成配置目录与模板）：
sh
```
python3 <skill-dir>/scripts/monitor.py setup
```
编辑配置 ~/.config/resource-monitor/config.yaml，填入：
- smtp：SMTP 服务器、账号、授权码（国内邮箱 QQ/163 均可；QQ 用「授权码」而非登录密码）
- metrics：CPU/内存/磁盘阈值
- window：允许发送的时间窗口（可选）
- cooldown_minutes：通知频率（可选）
SMTP 密码建议写入独立文件 ~/.config/resource-monitor/.smtp_secret（chmod 600），配置文件只引用路径。

校验 + 安装定时任务：

python3 <skill-dir>/scripts/monitor.py validate-config
python3 <skill-dir>/scripts/monitor.py send-test       # 收一封测试邮件
bash <skill-dir>/assets/install.sh                     # 自动写入 crontab

Claude 交互：用户说「看下服务器负载」→ 运行 status；「测一下告警邮件」→ send-test；「帮我配置监控」→ 引导用户完成 setup + 编辑 config.yaml + validate-config + send-test。

2. 依赖

Python ≥ 3.9
psutil、pyyaml、jinja2（第三方，安装时可用国内镜像加速）

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple psutil pyyaml jinja2

模板渲染优先 jinja2；缺失时脚本自动回退到 Python 标准库 string.Template，功能不中断。

3. 文件布局

skill 目录（随版本更新，只读）：

路径	说明
`SKILL.md`	本文档
`scripts/monitor.py`	核心监控脚本（cron 直接调用）
`assets/config.example.yaml`	配置模板
`assets/install.sh`	一键安装辅助
`assets/templates/*.html`	邮件文案模板

运行时数据（用户环境，不受 skill 更新影响）：

路径	说明
`~/.config/resource-monitor/config.yaml`	用户配置
`~/.config/resource-monitor/.smtp_secret`	SMTP 密码（chmod 600）
`~/.local/state/resource-monitor/state.json`	运行状态（告警去重/节流）
`~/.local/state/resource-monitor/monitor.log`	运行日志

4. 发送决策模型

一份邮件聚合列出所有超限指标（不是每项一封）。状态机基于 state.json：

状态变化去重：只有指标从「正常 → 超限」才进入告警状态；恢复后重置，下次超限重新计时。
cooldown 节流：同一告警两次实际发送之间强制最小间隔 cooldown_minutes，防止刷屏。
单日上限：daily_cap 限制当日发送总数，防止异常失控。
时间窗口：window.rules 之外即使超限也静默不发，但状态照常记录、不推进上次发送时间——窗口一打开的第一轮检查就会补发（夜间超限、早上准时收到）。
恢复通知：recovery: true 时，恢复正常会发一封恢复邮件（受 cooldown 与窗口约束）。

决策优先级：冷却期内 → 当日已达上限 → 窗口外静默 → 发送。

5. 配置参考

见 assets/config.example.yaml（带注释的完整示例）。校验命令：

python3 <skill-dir>/scripts/monitor.py validate-config --smtp-connect

--smtp-connect 会额外执行 SMTP 连接与认证握手（不发信）。

6. 模板编写

模板文件在 assets/templates/，使用 Jinja2 语法。可在 config.yaml → templates 修改主题与正文文件名。

暴露给模板的变量白名单（SMTP 凭据绝不会进入模板上下文）：

变量	说明
`hostname`	服务器名（`hostname_label` 或系统主机名）
`timestamp`	本地时间 `YYYY-MM-DD HH:MM:SS`
`status`	`alarm` / `recovery` / `test`
`alarm_count`	超限指标个数
`alarms`	`[{metric, current, threshold, path}]` 超限指标列表
`metrics`	全量指标 `{key: {percent, threshold, path}}`
`uptime`	运行时长（timedelta）
`load_avg`	`psutil.getloadavg()` 三元组

subject 同样支持模板变量，如 [{{ hostname }}] 资源告警 ({{ alarm_count }}项)。

7. cron

脚本由 cron 定时运行，每 5 分钟一次全天运行；时间窗口在脚本内过滤（二者正交，改窗口不影响 cron）。

text

*/5 * * * * /usr/bin/python3 ~/.claude/skills/wzz-server-monitor/scripts/monitor.py check --config ~/.config/resource-monitor/config.yaml >> ~/.local/state/resource-monitor/monitor.log 2>&1

使用绝对路径 python3，不依赖 cron 的 PATH。
检查频率决定「多久看一次」，通知频率由 cooldown_minutes 控制。
bash assets/install.sh 可自动写入并去重 crontab。

WSL2 / 容器 cron 自启

WSL2 与多数容器默认不启动 cron 服务。手动启动：

sudo service cron start

开机自启（WSL2）：编辑 /etc/wsl.conf：

ini

[boot]
command = service cron start

8. 日常维护

需求	命令
查看当前指标与状态	`monitor.py status`
手动触发一次检查	`monitor.py check --dry-run`（只打印决策）
绕过窗口测试	`monitor.py check --now`
重置告警状态	`monitor.py reset-state`
修改配置后校验	`monitor.py validate-config`

日志位置 ~/.local/state/resource-monitor/monitor.log，长跑后手动截断（> log）。

9. 故障排查

现象	排查
SMTP 认证失败	QQ/163 邮箱必须用「授权码」（设置里生成）而非登录密码；检查 `security`/`port` 是否匹配（ssl=465, tls=587）
日志为空	检查 cron 服务是否运行（WSL2 见上）；`crontab -l` 确认条目
CPU 恒为 0%	cron 每轮是全新进程，`cpu_interval` 必须 > 0（默认 0.5）
窗口内仍没收到	`validate-config` 确认时间格式；`status` 查看 `window: 开/关`
不想收到重复告警	调大 `cooldown_minutes` 或开启 `recovery` 恢复通知

10. 在其他 Agent 中使用（Claude / Codex 等）

本 skill 遵循 Agent Skills 开放标准，核心格式（SKILL.md + YAML frontmatter + Markdown）在 Claude Code、OpenAI Codex、Cursor 等主流 Agent 间通用：

本文件的 name/description/version 是通用字段；user-invocable、allowed-tools 是 Claude Code 增强，其他 Agent 会忽略。
监控功能本身与 Agent 无关：即使不经过任何 Agent，cron 直接运行 scripts/monitor.py check 即可工作。

在 Codex 等其他 Agent 中使用时，把本 skill 目录软链到它的 skills 发现路径：

mkdir -p ~/.codex/skills   # 或 .agents/skills
ln -s <skill-dir> ~/.codex/skills/wzz-server-monitor

11. 安全说明

SMTP 密码存 ~/.config/resource-monitor/.smtp_secret（chmod 600），不写入配置文件。
模板上下文只注入白名单变量，凭据与完整配置不进模板。
脚本只读取系统指标与发送邮件，不做任何删除/修改系统操作。
发布版本不包含任何用户数据；config.yaml、state.json、.smtp_secret 均生成于用户本地目录。