email-imap-fetch

Email IMAP Fetch

核心目标

• 使用 IMAP IDLE 等待新邮件。
• 每次唤醒后获取未读邮件。
• 支持通过环境变量配置多个邮箱账户。
• 严格通过环境变量模式（idle 或 poll）控制 IDLE 支持，不进行运行时探测。
• 将获取的每封邮件转发到 OpenClaw Webhook。
• 输出机器可读的 JSON 行，供下游步骤使用。
• 严格将此技能限制在第 1 阶段的路由模式：仅发送摘要片段和结构化引用，不发送完整的原始邮件正文，也不发送附件二进制内容。

工作流

1. 配置账户环境变量和 OpenClaw Webhook 环境变量（参见 references/env.md 和 assets/config.example.env）。
2. 验证配置：

python3 scripts/imap_idle_fetch.py check-config

3. 为每个账户运行一个 IDLE 周期（冒烟测试）：

python3 scripts/imap_idle_fetch.py listen --cycles 1 --idle-seconds 120 --max-messages 10

4. 持续运行（默认常驻模式）：

python3 scripts/imap_idle_fetch.py listen

运行时模型

• 技能文件会安装在本地，但监听器不会自动启动。
• 在 idle 模式下，只有监听器进程和 IMAP 连接保持运行时，IMAP IDLE 才会接收推送事件。
• 在 poll 模式下，监听器会休眠指定的轮询间隔，然后获取未读邮件。
• 如果进程退出，就会错过推送事件；下次运行仍可使用 UNSEEN 获取现有未读邮件。
• 默认运行时为常驻模式（默认 IMAP_CYCLES=0）。
• 默认 IDLE 模式为 poll（适用于不支持 IDLE 的服务器，更安全）。
• 在生产环境中，始终运行的部署必须由 systemd、launchd、supervisor 或同等的守护进程管理器运行。
• 不要将监听器作为绑定到交互式 exec 会话的前台进程运行；会话一旦退出，监听器也会停止。

输出约定

• 输出格式为 JSONL（每行一个 JSON 对象）。
• 生命周期事件使用 type=status。
• 获取的邮件使用 type=message，包含：
  • account、mailbox、seq、uid
  • subject、from、to、date
  • message_id_raw、message_id_norm（以及兼容字段 message_id）
  • snippet（仅包含纯文本预览）
  • attachment_count、attachment_manifest（仅包含摘要，不含附件内容）
  • 机器可读的 mail_ref 对象（account、mailbox、uid、message_id_raw、message_id_norm、date）
• Webhook 消息包含两个固定的机器可读区块，用于确定性地提取分发信息：
  • <<<MAIL_REF_JSON>>> ... <<<END_MAIL_REF_JSON>>>
  • <<<ATTACHMENT_MANIFEST_JSON>>> ... <<<END_ATTACHMENT_MANIFEST_JSON>>>
• 周期状态输出中的 wait_mode 为 idle 或 poll。
• wait_events 记录当前等待策略的详细信息。
• OpenClaw Webhook POST 成功时输出 event=webhook_delivered 状态事件。
• 账户级故障使用 type=error。
• OpenClaw Webhook POST 失败时输出 event=webhook_failed 错误事件。

参数

• --cycles：每个账户的 IDLE 周期数（0 表示无限）。
• --idle-seconds：每次 IDLE 调用的最长等待时间。
• --poll-seconds：轮询模式启用时使用的间隔。
• --idle-mode：idle 或 poll。
• --max-messages：每个周期获取的未读邮件数上限。
• --mark-seen / --no-mark-seen：控制是否更新未读状态。
• --snippet-chars：预览长度上限。
• --connect-timeout：连接超时秒数。
• --retry-seconds：失败后的重试延迟。

环境变量默认值：

• IMAP_CYCLES
• IMAP_IDLE_MODE
• IMAP_IDLE_SECONDS
• IMAP_POLL_SECONDS
• IMAP_MAX_MESSAGES
• IMAP_MARK_SEEN
• IMAP_SNIPPET_CHARS
• IMAP_CONNECT_TIMEOUT
• IMAP_RETRY_SECONDS

OpenClaw Webhook 转发：

• OPENCLAW_WEBHOOKS_ENABLED
• OPENCLAW_WEBHOOKS_TOKEN
• OPENCLAW_WEBHOOKS_BASE_URL
• OPENCLAW_WEBHOOKS_MODE（agent 或 wake）
• OPENCLAW_WEBHOOKS_ENDPOINT（可选的端点覆盖项）
• OPENCLAW_WEBHOOKS_PATH
• OPENCLAW_WEBHOOKS_WAKE_MODE
• OPENCLAW_WEBHOOKS_DELIVER
• OPENCLAW_WEBHOOKS_TIMEOUT
• OPENCLAW_WEBHOOKS_NAME
• OPENCLAW_WEBHOOKS_AGENT_ID
• OPENCLAW_WEBHOOKS_CHANNEL
• OPENCLAW_WEBHOOKS_TO
• OPENCLAW_WEBHOOKS_MODEL
• OPENCLAW_WEBHOOKS_THINKING
• OPENCLAW_WEBHOOKS_AGENT_TIMEOUT_SECONDS
• OPENCLAW_WEBHOOKS_SESSION_KEY_PREFIX

错误处理

• 无效的环境变量配置会以代码 2 退出。
• 在 idle 模式下，不支持 IDLE 时会返回明确的错误，并建议设置 IMAP_IDLE_MODE=poll。
• 运行时故障会以 type=error 的形式输出。
• 账户处理过程中出现错误时，命令会以非零状态码退出。

参考

• references/env.md

资源

• assets/config.example.env

脚本

• scripts/imap_idle_fetch.py