Gmail Alert Monitor

注意事项

• 不要把真实 .env 打包或提交
• 不要把真实 state/notified.json 打包或提交
• macOS 自动运行建议使用 launchd，而不是传统 cron

当前能力

已支持：

• Gmail API OAuth 2.0 认证
• 规则化邮件搜索
• 发件人 / 主题 / 正文关键词匹配
• 金额提取
• JSON 输出
• 中文预警文案生成
• 调试真实邮箱搜索结果
• OpenClaw 单入口执行
• OpenClaw JSON 契约输出（供调度层消费）
• 基于 messageId 的去重

当前版本暂未直接内置：

• Telegram 消息发送逻辑（由 OpenClaw 侧负责）
• OpenClaw cron 自动配置
• 多账号支持
• 状态自动清理

核心脚本

scripts/auth-test.js

测试 Gmail OAuth 是否可用。

scripts/check-alert.js

执行 Gmail 邮件检测并输出结构化 JSON。

scripts/debug-search.js

调试真实邮箱中的邮件搜索结果。

scripts/build-alert-message.js

把检测结果转换成适合 Telegram 使用的中文预警文案。

scripts/run-openclaw-check.js

给 OpenClaw 使用的统一入口脚本。

功能：

• 执行检测
• 做去重判断
• 输出最终预警文案
• 没有新预警时输出 NO_ALERT
• 支持 --json 输出结构化契约，供 OpenClaw 调度层读取

依赖要求

• Node.js 18+
• npm
• Gmail API OAuth 凭证
• .env 配置文件
• rules.json 规则文件

基本使用流程

1. 配置 Gmail OAuth
2. 复制模板生成 .env 和 rules.json
3. 执行 npm install
4. 执行 npm run auth:test
5. 执行 npm run openclaw:check 或 npm run openclaw:check:json
6. 由 OpenClaw 调度层读取输出结果，并接入 Telegram 消息发送链路

配置文件

.env

GMAIL_CLIENT_ID=...
GMAIL_CLIENT_SECRET=...
GMAIL_REFRESH_TOKEN=...
GMAIL_USER_ID=me

ALERT_NOTIFY_ENABLED=true
ALERT_NOTIFY_CHANNEL=telegram
ALERT_NOTIFY_TO=7600789277
ALERT_STATE_FILE=./state/notified.json

rules.json

{
  "version": 1,
  "rules": [
    {
      "name": "gptproto-low-balance",
      "enabled": true,
      "from": ["[email protected]"],
      "subjectIncludes": ["balance", "dropped"],
      "bodyIncludes": [
        "account balance has dropped",
        "recharge your account",
        "billing section"
      ],
      "threshold": 20,
      "currency": "USD",
      "search": {
        "maxResults": 10,
        "newerThanDays": 7
      }
    }
  ]
}

与 OpenClaw 的职责边界

推荐职责拆分：

• Skill：检测、去重、消息构建、输出文本或 JSON 契约
• OpenClaw：定时调度、消费 JSON、决定是否发送、选择渠道、实际发送 Telegram 消息

当前版本不建议：

• Skill 直接调用 Telegram Bot API
• Skill 直接耦合 OpenClaw 发消息命令

推荐阅读文档

• docs/oauth-setup.md
• docs/usage.md
• docs/openclaw-integration.md
• docs/troubleshooting.md