好奇心花园🪴

搜索

SearchSearch

最近的笔记

电子邮件

2026年5月24日8分钟阅读

电子邮件设置

Hermes 可以使用标准的 IMAP 和 SMTP 协议接收和回复电子邮件。向 agent 的地址发送电子邮件，它会在同一线程中回复——无需特殊的客户端或机器人 API。适用于 Gmail、Outlook、Yahoo、Fastmail 或任何支持 IMAP/SMTP 的提供商。

:::info 无外部依赖 电子邮件适配器使用 Python 内置的 imaplib、smtplib 和 email 模块。无需额外的包或外部服务。 :::

前提条件

  • 一个专用的电子邮件账户用于您的 Hermes agent（不要使用您的个人邮箱）
  • 在电子邮件账户上启用 IMAP
  • 一个应用密码（如果使用 Gmail 或其他需要双重验证的提供商）

Gmail 设置

  1. 在您的 Google 账户上启用双重验证
  2. 前往应用密码
  3. 创建一个新的应用密码（选择”邮件”或”其他”）
  4. 复制 16 位密码——您将用它代替常规密码

Outlook / Microsoft 365

  1. 前往安全设置
  2. 如尚未启用，启用双重验证
  3. 在”其他安全选项”下创建应用密码
  4. IMAP 主机：outlook.office365.com，SMTP 主机：smtp.office365.com

其他提供商

大多数电子邮件提供商支持 IMAP/SMTP。请查看您的提供商的文档，了解：

  • IMAP 主机和端口（通常为 993，使用 SSL）
  • SMTP 主机和端口（通常为 587，使用 STARTTLS）
  • 是否需要应用密码

第 1 步：配置 Hermes

最简单的方式：

hermes gateway setup

从平台菜单中选择电子邮件。向导会提示您输入电子邮件地址、密码、IMAP/SMTP 主机和允许的发送者。

手动配置

添加到 ~/.hermes/.env：

# 必需
EMAIL_ADDRESS=hermes@gmail.com
EMAIL_PASSWORD=abcd efgh ijkl mnop    # 应用密码（不是您的常规密码）
EMAIL_IMAP_HOST=imap.gmail.com
EMAIL_SMTP_HOST=smtp.gmail.com
 
# 安全（推荐）
EMAIL_ALLOWED_USERS=your@email.com,colleague@work.com
 
# 可选
EMAIL_IMAP_PORT=993                    # 默认值：993（IMAP SSL）
EMAIL_SMTP_PORT=587                    # 默认值：587（SMTP STARTTLS）
EMAIL_POLL_INTERVAL=15                 # 收件箱检查间隔秒数（默认：15）
EMAIL_HOME_ADDRESS=your@email.com      # 定时任务的默认投递目标

第 2 步：启动网关

hermes gateway              # 前台运行
hermes gateway install      # 安装为用户服务
sudo hermes gateway install --system   # 仅 Linux：开机自启系统服务

启动时，适配器：

  1. 测试 IMAP 和 SMTP 连接
  2. 将所有现有收件箱消息标记为”已读”（仅处理新邮件）
  3. 开始轮询新消息

工作原理

接收消息

适配器以可配置的时间间隔（默认：15 秒）轮询 IMAP 收件箱中的未读消息。对于每封新邮件：

  • 主题行作为上下文包含在内（例如 [Subject: Deploy to production]）
  • 回复邮件（主题以 Re: 开头）跳过主题前缀——线程上下文已建立
  • 附件本地缓存：
    • 图片（JPEG、PNG、GIF、WebP）→ 可供视觉工具使用
    • 文档（PDF、ZIP 等）→ 可供文件访问
  • 仅 HTML 的邮件会去除标签以提取纯文本
  • 自身消息会被过滤掉以防止回复循环
  • 自动/无回复发送者会被静默忽略——noreply@、mailer-daemon@、bounce@、no-reply@，以及带有 Auto-Submitted、Precedence: bulk 或 List-Unsubscribe 标头的邮件

发送回复

回复通过 SMTP 发送，带有正确的邮件线程化：

  • In-Reply-To 和 References 标头维护线程
  • 主题行保留并带有 Re: 前缀（不会出现双重 Re: Re:）
  • Message-ID 使用 agent 的域名生成
  • 回复以纯文本（UTF-8）发送

文件附件

agent 可以在回复中发送文件附件。在回复中包含 MEDIA:/path/to/file，该文件会附加到出站邮件中。

跳过附件

要忽略所有传入附件（用于恶意软件保护或节省带宽），请添加到您的 config.yaml：

platforms:
  email:
    skip_attachments: true

启用后，附件和内联部分在载荷解码之前被跳过。邮件正文文本仍然正常处理。

访问控制

电子邮件访问遵循与所有其他 Hermes 平台相同的模式：

  1. 设置了 EMAIL_ALLOWED_USERS → 仅处理来自这些地址的邮件
  2. 未设置白名单 → 未知发送者获得配对码
  3. 设置了 EMAIL_ALLOW_ALL_USERS=true → 接受任何发送者（谨慎使用）

:::warning 始终配置 EMAIL_ALLOWED_USERS。 否则，任何知道 agent 电子邮件地址的人都可以发送命令。agent 默认具有终端访问权限。 :::

故障排除

问题解决方案
启动时”IMAP connection failed”验证 EMAIL_IMAP_HOST 和 EMAIL_IMAP_PORT。确保账户上已启用 IMAP。对于 Gmail，在设置 → 转发和 POP/IMAP 中启用。
启动时”SMTP connection failed”验证 EMAIL_SMTP_HOST 和 EMAIL_SMTP_PORT。检查您的密码是否正确（对于 Gmail 使用应用密码）。
未收到消息检查 EMAIL_ALLOWED_USERS 是否包含发送者的电子邮件。检查垃圾邮件文件夹——某些提供商会标记自动回复。
“Authentication failed”对于 Gmail，您必须使用应用密码，而不是常规密码。确保先启用双重验证。
重复回复确保只有一个网关实例在运行。检查 hermes gateway status。
响应慢默认轮询间隔为 15 秒。使用 EMAIL_POLL_INTERVAL=5 减少间隔以获得更快响应（但会增加 IMAP 连接次数）。
回复未线程化适配器使用 In-Reply-To 标头。某些电子邮件客户端（尤其是基于 Web 的）可能无法正确对自动消息进行线程化。

安全性

:::warning 使用专用的电子邮件账户。 不要使用您的个人邮箱——agent 在 .env 中存储密码，并通过 IMAP 拥有完整的收件箱访问权限。 :::

  • 使用应用密码代替您的主密码（Gmail 使用双重验证时需要）
  • 设置 EMAIL_ALLOWED_USERS 以限制谁可以与 agent 交互
  • 密码存储在 ~/.hermes/.env 中——保护此文件（chmod 600）
  • IMAP 默认使用 SSL（端口 993），SMTP 默认使用 STARTTLS（端口 587）——连接已加密

环境变量参考

变量必需默认值描述
EMAIL_ADDRESS是—Agent 的电子邮件地址
EMAIL_PASSWORD是—电子邮件密码或应用密码
EMAIL_IMAP_HOST是—IMAP 服务器主机（例如 imap.gmail.com）
EMAIL_SMTP_HOST是—SMTP 服务器主机（例如 smtp.gmail.com）
EMAIL_IMAP_PORT否993IMAP 服务器端口
EMAIL_SMTP_PORT否587SMTP 服务器端口
EMAIL_POLL_INTERVAL否15收件箱检查间隔秒数
EMAIL_ALLOWED_USERS否—逗号分隔的允许发送者地址
EMAIL_HOME_ADDRESS否—定时任务的默认投递目标
EMAIL_ALLOW_ALL_USERS否false允许所有发送者（不推荐）

关系图谱

反向链接