邮件设置
Hermes 可以使用标准的 IMAP 和 SMTP 协议接收和回复邮件。向代理的邮箱地址发送邮件，它会以线程方式回复——无需特殊客户端或机器人 API。支持 Gmail、Outlook、Yahoo、Fastmail 或任何支持 IMAP/SMTP 的邮件服务商。
无外部依赖
邮件适配器使用 Python 内置的 imaplib、smtplib 和 email 模块。无需额外安装包或外部服务。
前提条件
- 专用邮箱账户：用于你的 Hermes 代理（不要使用个人邮箱）
- 邮箱账户已启用 IMAP
- 若使用 Gmail 或其他启用了双因素认证（2FA）的服务，需使用应用密码
Gmail 设置
- 在你的 Google 账户中启用双因素认证
- 访问 应用密码
- 创建一个新的应用密码（选择“邮件”或“其他”）
- 复制 16 位字符的密码——你将用它代替常规密码
Outlook / Microsoft 365
- 访问 安全设置
- 如果尚未启用，请开启 2FA
- 在“其他安全选项”下创建应用密码
- IMAP 主机：
outlook.office365.com，SMTP 主机：smtp.office365.com
其他服务商
大多数邮件服务商都支持 IMAP/SMTP。请查阅服务商文档以确认：
- IMAP 主机和端口（通常为 993 端口，使用 SSL）
- SMTP 主机和端口（通常为 587 端口，使用 STARTTLS）
- 是否需要应用密码
第一步：配置 Hermes
最简单的方式：
hermes gateway setup
从平台菜单中选择 邮件。向导将提示你输入邮箱地址、密码、IMAP/SMTP 主机以及允许的发件人。
手动配置
将以下内容添加至 ~/.hermes/.env：
# Required
EMAIL_ADDRESS=hermes@gmail.com
EMAIL_PASSWORD=abcd efgh ijkl mnop # App password (not your regular password)
EMAIL_IMAP_HOST=imap.gmail.com
EMAIL_SMTP_HOST=smtp.gmail.com
# Security (recommended)
EMAIL_ALLOWED_USERS=your@email.com,colleague@work.com
# Optional
EMAIL_IMAP_PORT=993 # Default: 993 (IMAP SSL)
EMAIL_SMTP_PORT=587 # Default: 587 (SMTP STARTTLS)
EMAIL_POLL_INTERVAL=15 # Seconds between inbox checks (default: 15)
EMAIL_HOME_ADDRESS=your@email.com # Default delivery target for cron jobs
第二步：启动网关
hermes gateway # Run in foreground
hermes gateway install # Install as a user service
sudo hermes gateway install --system # Linux only: boot-time system service
启动时，适配器会：
- 测试 IMAP 和 SMTP 连接
- 将收件箱中所有现有邮件标记为“已读”（仅处理新邮件）
- 开始轮询新邮件
工作原理
接收消息
适配器以可配置的间隔（默认 15 秒）轮询 IMAP 收件箱中的“未读”邮件。对于每封新邮件：
- 主题行 作为上下文包含在内（例如：
[Subject: 部署到生产环境]） - 回复邮件（主题以
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 使用代理域名生成
- 回复以纯文本格式发送（UTF-8 编码）
文件附件
代理可在回复中发送文件附件。在响应中包含 MEDIA:/path/to/file，文件将作为附件附加到发送的邮件中。
忽略附件
为防止恶意软件或节省带宽，可忽略所有传入附件。在 config.yaml 中添加：
platforms:
email:
skip_attachments: true
启用后，附件和内联部分将在负载解码前被跳过。邮件正文文本仍会正常处理。
访问控制
邮件访问遵循 Hermes 所有平台的相同模式：
- 设置了
EMAIL_ALLOWED_USERS→ 仅处理来自这些地址的邮件 - 未设置允许列表 → 未知发件人将收到配对码
EMAIL_ALLOW_ALL_USERS=true→ 接受任何发件人（请谨慎使用）
注意
始终配置 EMAIL_ALLOWED_USERS。 若未配置，任何知道代理邮箱地址的人都可发送命令。代理默认具有终端访问权限。
故障排除
| 问题 | 解决方案 |
|---|---|
| 启动时出现 "IMAP连接失败" | 验证 EMAIL_IMAP_HOST 和 EMAIL_IMAP_PORT。确保账户已启用IMAP。对于Gmail，请在设置 → 转发和POP/IMAP中启用。 |
| 启动时出现 "SMTP连接失败" | 验证 EMAIL_SMTP_HOST 和 EMAIL_SMTP_PORT。检查密码是否正确（Gmail需使用应用密码）。 |
| 未收到消息 | 检查 EMAIL_ALLOWED_USERS 是否包含发件人邮箱。检查垃圾邮件文件夹——某些服务商可能会标记自动回复。 |
| "认证失败" | 对于Gmail，必须使用应用密码，而非常规密码。请先确保已启用双重验证（2FA）。 |
| 重复回复 | 确保仅运行一个网关实例。检查 hermes gateway status。 |
| 响应缓慢 | 默认轮询间隔为15秒。可通过设置 EMAIL_POLL_INTERVAL=5 降低间隔以加快响应（但会增加IMAP连接数）。 |
| 回复无法线程化 | 适配器使用 In-Reply-To 头部。某些邮件客户端（尤其是基于网页的）可能无法正确对自动化消息进行线程化。 |
安全性
注意
请使用专用邮箱账户。 不要使用个人邮箱——该代理会将密码存储在 .env 文件中，并通过IMAP拥有对收件箱的完全访问权限。
- 使用 应用密码 而非主密码（Gmail启用2FA时必需）
- 设置
EMAIL_ALLOWED_USERS以限制可与代理交互的用户 - 密码存储于
~/.hermes/.env—— 请保护该文件（使用chmod 600） - IMAP 默认使用 SSL（端口 993），SMTP 默认使用 STARTTLS（端口 587）——连接均为加密
环境变量参考
| 变量 | 是否必需 | 默认值 | 说明 |
|---|---|---|---|
EMAIL_ADDRESS | 是 | — | 代理的邮箱地址 |
EMAIL_PASSWORD | 是 | — | 邮箱密码或应用密码 |
EMAIL_IMAP_HOST | 是 | — | IMAP服务器主机（例如：imap.gmail.com） |
EMAIL_SMTP_HOST | 是 | — | SMTP服务器主机（例如：smtp.gmail.com） |
EMAIL_IMAP_PORT | 否 | 993 | IMAP服务器端口 |
EMAIL_SMTP_PORT | 否 | 587 | SMTP服务器端口 |
EMAIL_POLL_INTERVAL | 否 | 15 | 检查收件箱的间隔秒数 |
EMAIL_ALLOWED_USERS | 否 | — | 用逗号分隔的允许发件人地址列表 |
EMAIL_HOME_ADDRESS | 否 | — | 定时任务（cron jobs）的默认投递目标 |
EMAIL_ALLOW_ALL_USERS | 否 | false | 允许所有发件人（不推荐） |