Mail Agent

核心用法

mail-agent 是一款运行于 OpenClaw 生态的 AI 邮件监控插件，实现 Gmail 收件箱的实时监听与智能告警。其完整部署流程涵盖八大步骤：首先验证 gog 认证工具已配置 Gmail 账户权限；随后通过 gcloud CLI 完成 Google Cloud 身份验证与项目初始化；启用 Gmail 与 Pub/Sub API 后，创建消息主题及订阅，并授权 Gmail 服务账号发布权限；接着通过 OpenClaw 插件系统安装主程序；配置 Telegram 聊天 ID、GCP 项目 ID、订阅名称等必填参数，可选接入 LLM（如 GPT-4o-mini）实现邮件重要性智能分类；重启网关后即可建立持久化推送通道。测试阶段建议发送带"Urgent"关键词的模拟邮件验证链路。

显著优点

• 实时推送：基于 Google Pub/Sub 原生推送机制，延迟控制在秒级，优于传统轮询方案
• AI 智能过滤：内置 LLM 分类能力，可自动识别紧急事务邮件，减少信息噪音
• OpenClaw 原生集成：作为官方插件生态一员，享受统一配置管理与日志监控能力
• 低运维成本：依托 Google 托管服务，无需自建消息队列或持久化存储

潜在局限与风险

• 多账号绑定限制：需手动指定 GOG_ACCOUNT，多邮箱场景配置复杂度倍增
• LLM 可选但推荐：若跳过 LLM 配置，插件退化为纯透传模式，失去核心价值
• Telegram 单点依赖：告警通道仅限 Telegram，未内置备用推送方案（如邮件、Webhook）
• GCP 资源持续性：Pub/Sub 订阅与主题长期运行可能产生微量费用，需关注账单
• 权限模型较宽：gmail-api-push@system.gserviceaccount.com 的 Publisher 角色授权需信任 Google 内部服务账号

适合人群

DevOps 工程师、独立开发者、运维值班人员及需要即时感知关键邮件的技术团队，尤其适用于监控服务器告警、安全审计通知、CI/CD 状态报告等场景。

常规风险提示

• 配置过程中涉及 GCP 项目创建与 API 启用，需具备 GCP 基础操作经验
• llmApiKey 以明文形式存储于 OpenClaw 配置系统，建议配合环境变量或密钥管理服务使用
• 测试阶段需确保 Telegram Bot 权限正常，避免 telegram runtime not available 类错误

核心用法

mail-agent 是一款面向 OpenClaw 平台的 Gmail 智能监控插件，通过 Google Pub/Sub 实现邮件事件的实时推送。用户完成安装后，插件会持续监听指定 Gmail 账户的新邮件，利用可选的 LLM（如 GPT-4o-mini）对邮件内容进行智能重要性分类，最终将判定为"紧急"或"重要"的邮件推送至用户指定的 Telegram 聊天会话。

整个部署流程分为八个步骤：首先需要配置 gog 认证以获取 Gmail 访问权限，其次设置 Google Cloud 项目并启用 Gmail 与 Pub/Sub API，接着创建主题和订阅并授权 Gmail 服务账号，然后安装插件、配置 Telegram chatId 和 GCP 项目 ID 等关键参数，最后重启 OpenClaw 网关并验证日志输出。测试阶段建议发送包含"urgent"、"server down"等关键词的邮件触发完整链路验证。

显著优点

1. 实时性架构：采用 Google Pub/Sub 推送机制替代传统轮询，邮件到达后秒级触发通知，延迟远低于 IMAP 轮询方案。
2. AI 智能过滤：集成 LLM 进行语义级重要性判断，可识别"服务器宕机""支付失败"等业务关键场景，有效减少通知噪音。
3. 多平台打通：无缝对接 Gmail 与 Telegram 两大平台，适合已深度使用这两种服务的用户群体。
4. 配置透明：采用显式配置驱动架构，所有敏感信息（API 密钥、项目 ID）均由用户自主掌控，无硬编码或隐蔽收集行为。
5. 开源可审计：MIT 许可证下的 TypeScript 代码，结构清晰、依赖明确，便于技术用户审查安全性和定制扩展。

潜在缺点与局限性

1. 部署门槛较高：需要同时掌握 Google Cloud 项目管理、IAM 权限配置、Pub/Sub 主题订阅设置以及 Telegram Bot 交互，对非技术用户形成显著障碍。
2. 基础设施依赖：强制依赖 Google Cloud 项目，即使个人使用也需承担潜在的云服务费用（Pub/Sub 消息量较大时），且需维护 GCP 账单和配额监控。
3. LLM 成本与隐私权衡：智能分类功能依赖外部 LLM API，邮件内容需外传至第三方服务（默认 OpenAI），带来数据隐私顾虑和持续的成本支出；若关闭 LLM 则退化为全量转发，失去过滤价值。
4. 单点故障风险：链路涉及 Gmail API、Pub/Sub、OpenClaw 网关、Telegram Bot 四个环节，任一服务异常均导致通知中断，且错误排查需要查看多层日志。
5. 功能单一性：仅支持"接收-判断-推送"单向流程，无法回复邮件、无法多账户管理、无法自定义复杂的分类规则或通知模板。

适合的目标群体

• 运维工程师/SRE：需要 7×24 小时掌握服务器告警、监控邮件的技术人员
• 创业者/小团队负责人：业务关键信息分散在 Gmail，需要聚合到常用的 Telegram 进行快速响应
• 自由职业者：客户邮件量大，希望 AI 筛选出高优先级商机或紧急需求
• 技术爱好者：熟悉 GCP 和 Linux 环境，愿意自建监控基础设施的 DIY 用户

不适合：无技术背景的普通用户、对数据隐私极度敏感且不愿使用云服务的企业、仅需简单邮件提醒的轻度需求场景。

使用风险与注意事项

性能与稳定性：Pub/Sub 订阅需要保持长连接，网络波动可能导致 watch 注册失效，需定期检查 openclaw gateway logs 确认 watch registered 状态。若 LLM API 响应超时，邮件处理将延迟或进入降级模式。

密钥安全：GCP 服务账号密钥、Telegram Bot Token、OpenAI API Key 均属于高敏感信息，建议使用环境变量或 OpenClaw 的加密配置机制存储，避免以明文形式写入 shell 历史记录或配置文件。

成本控制：GCP Pub/Sub 按消息量计费，高频邮件场景（如订阅大量邮件列表）可能产生意外费用；LLM API 调用按 token 计费，需关注分类邮件的 token 消耗量。

隐私合规：邮件内容发送至第三方 LLM 服务商时，需确认其数据处理条款符合自身合规要求，敏感行业用户建议部署本地 LLM 或禁用智能分类功能。

长期维护：作为 T3 级别的个人开源项目，更新频率和社区支持存在不确定性，建议关注 GitHub 仓库的 commit 活跃度和 issue 响应情况，做好自行维护或迁移的心理准备。