imap-idle

📬 实时邮件监控与Webhook推送

基于IMAP IDLE协议实现事件驱动邮件监控,替代轮询检查,零Token等待,支持多账户与安全密钥存储,为OpenClaw提供即时邮件通知能力。

收藏
4.3k
安装
1.3k
版本
v1.4.0
CLS 安全性认证2026-06-04
点击查看完整报告 >

使用说明

核心用法

这是一个基于IMAP IDLE协议的事件驱动邮件监控工具,专为OpenClaw设计。用户通过交互式向导配置IMAP账户和本地Webhook端点后,工具会在后台建立持久的IMAP连接。当服务器收到新邮件时,会立即通过Webhook推送通知到OpenClaw,实现秒级响应。支持多账户并发监控、智能防抖(Debouncing)批量处理、以及系统级密钥库存储密码。

显著优点

1. 极致效率:相比传统轮询(每小时检查),实现零Token等待,仅在邮件到达时消耗资源,可节省90%以上Token。
2. 实时响应:从邮件到达至Webhook触发延迟小于1秒,远优于轮询模式的平均30分钟延迟。

3. 安全可靠:支持macOS Keychain、GNOME Keyring等系统级加密存储,避免密码明文保存在配置文件。

4. 智能处理:自动防抖机制可批量处理邮件风暴(如GitHub通知),单封邮件发送详情,多封邮件发送摘要。

5. 生产就绪:支持Systemd服务化部署,具备完善的错误重试、连接保活(Keep-alive)、UID去重机制。

潜在缺点或局限性

1. 依赖持续网络连接:需要保持与IMAP服务器的长期TCP连接,在网络不稳定环境下可能频繁重连。
2. 协议限制:仅支持支持IMAP IDLE协议的服务器(主流邮箱如Gmail、Outlook均支持,但部分企业邮箱可能限制)。

3. 本地部署复杂度:需要Python环境、依赖安装和配置文件管理,对非技术用户有一定门槛。

4. 单点故障:作为本地常驻进程,若进程崩溃或机器重启(未配置Systemd),可能导致邮件监控中断。

5. 安全责任:虽然代码安全,但用户需自行确保Webhook端点可信,且需正确配置文件权限。

适合的目标群体

1. OpenClaw重度用户:需要实时邮件触发自动化工作流的用户。
2. 开发者与DevOps工程师:需要将邮件集成到CI/CD流程或自动化脚本的技术人员。

3. 效率优化者:希望减少API调用成本(Token消耗)的精细化运营者。

4. 自托管爱好者:拥有个人服务器或NAS,希望自建邮件通知系统的用户。

5. 小型团队:需要监控支持邮箱但无需购买昂贵SaaS服务的初创团队。

使用风险

1. 凭据泄露风险:若未使用Keyring且配置文件权限设置不当,IMAP密码可能以明文形式存储在磁盘上,建议严格遵循chmod 600设置。
2. 网络资源占用:长期保持IMAP连接可能消耗少量带宽和服务器连接数,部分免费邮箱提供商可能对长期连接有限制。

3. Webhook单点故障:若OpenClaw Gateway未运行或配置错误,邮件通知将丢失或堆积,建议配合健康检查使用。

4. 版本依赖风险:依赖imapclientkeyring库,若这些库未来版本出现安全漏洞,需要及时更新。

5. 调试复杂性:由于是后台守护进程,初次配置时若Webhook不通,排查需要查看日志文件,对新手不够友好。

安全解读

核心用法

imap-idle 是一款事件驱动的邮件监控工具,通过 IMAP IDLE 协议将传统的轮询检查替换为即时推送通知。用户配置 IMAP 账户后,工具会建立持久连接,在服务器端有新邮件时立即触发 OpenClaw webhook,实现亚秒级延迟的邮件处理。

显著优点

1. 极致的 Token 效率:传统轮询每小时检查一次,每天消耗 8,000-24,000 tokens;IDLE 模式下等待期间零 token 消耗,仅在实际收到邮件时产生成本,节省 90% 以上。

2. 即时响应:轮询模式最多延迟 1 小时,IDLE 模式延迟低于 1 秒,真正实现事件驱动架构。

3. 安全设计:优先使用系统 keyring(macOS Keychain、GNOME Keyring、Windows Credential Manager)加密存储密码,config 文件仅作回退,避免明文凭证泄露。

4. 生产级健壮性:内置防抖缓冲(10 秒批处理)、UID 去重、指数退避重连、多账户并发线程等机制,可应对 GitHub mention 风暴等突发场景。

潜在局限

  • IMAP 服务器依赖:需邮件服务商支持 IDLE 扩展(Gmail、Outlook、自建服务器等均支持,但部分企业邮箱可能受限)。
  • 长连接维护:需保持网络稳定,防火墙可能断开空闲连接;工具内置 5 分钟 NOOP 保活和 15 分钟强制重连来缓解。
  • 初始配置复杂度:相比简单轮询,需配置 webhook、SSL 证书验证、keyring 等组件。

适合人群

  • 高频邮件处理用户(开发者、社区运营、客服团队)
  • 对延迟敏感的工作流(安全告警、验证码接收、CI/CD 通知)
  • Token 用量焦虑的 OpenClaw 重度用户
  • 注重安全凭证管理的隐私敏感用户

常规风险

| 风险项 | 说明 | 缓解措施 |
|--------|------|----------|
| 配置文件权限 | 若不用 keyring,明文密码存在于 ~/.openclaw/imap-idle.json | chmod 600 设置严格权限,或强制启用 keyring |
| 网络断连 | 移动网络或严格防火墙环境可能中断长连接 | 工具自动重连,建议搭配 systemd 服务保活 |
| 邮件服务商限制 | 部分服务商对 IDLE 连接数或时长有限制 | 控制监控账户数量,遵守服务商条款 |

安全认证

CLS-Certify v2.1.0 全量扫描评定 Grade A(82 分),无危险函数、无硬编码密钥、无第三方数据外泄。网络流量仅限于用户配置的 IMAP 服务器(TLS 加密)和本地 OpenClaw webhook(127.0.0.1)。

imap-idle 内容

scripts文件夹
手动下载zip · 23.3 kB
listener_old.pytext/plain
请选择文件