电子邮件
Hermes 可以通过标准 IMAP 和 SMTP 协议接收并回复电子邮件。给 agent 的邮箱发邮件，它就会在线程内回复，无需专用客户端或 bot API。适用于 Gmail、Outlook、Yahoo、Fastmail，或任何支持 IMAP/SMTP 的邮箱服务。
无需额外依赖
Email 适配器使用 Python 内置的 imaplib、smtplib 和 email 模块，不需要额外安装 Python 包或外部服务。
前提条件
- 为 Hermes agent 准备一个专用邮箱账号（不要使用你的个人邮箱）
- 该邮箱账号已启用 IMAP
- 如果使用 Gmail 或其他启用了 2FA 的服务，需要应用专用密码
Gmail 设置
- 在 Google 账号中启用两步验证
- 打开 App Passwords
- 新建一个应用专用密码（选择 “Mail” 或 “Other”）
- 复制这串 16 位密码，后续用它替代普通登录密码
Outlook / Microsoft 365
- 打开 Security Settings
- 如未启用，则开启 2FA
- 在 “Additional security options” 下创建一个 App Password
- IMAP 主机：
outlook.office365.com，SMTP 主机：smtp.office365.com
其他邮箱服务
大多数邮箱服务都支持 IMAP/SMTP。查阅对应文档，确认：
- IMAP 主机和端口（通常是 993 + SSL）
- SMTP 主机和端口（通常是 587 + STARTTLS）
- 是否要求应用专用密码
第 1 步：配置 Hermes
最简单的方式：
hermes gateway setup
在平台列表里选择 Email。向导会提示你填写邮箱地址、密码、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
第 2 步：启动网关
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 收件箱中的 UNSEEN 邮件。对每一封新邮件：
- 邮件主题会作为上下文加入（例如
[Subject: Deploy to production]） - 回复邮件（主题以
Re:开头）会跳过主题前缀，因为线程上下文通常已经建立 - 附件会缓存在本地：
- 图片（JPEG、PNG、GIF、WebP）→ 可供视觉工具使用
- 文档（PDF、ZIP 等）→ 可供文件访问
- 纯 HTML 邮件会先去标签再提取纯文本
- 自己发给自己的邮件会被过滤，防止形成回复回路
- 自动邮件 / noreply 发件人会被静默忽略，如
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
启用后，附件和内联部分会在解码前被直接跳过，但邮件正文仍会正常处理。
访问控制
Email 平台与其他 Hermes 平台保持一致：
- 设置了
EMAIL_ALLOWED_USERS→ 仅处理这些地址发来的邮件 - 未设置 allowlist → 未知发件人会收到配对码
- 设置
EMAIL_ALLOW_ALL_USERS=true→ 接受任意发件人（请谨慎使用）
注意
务必配置 EMAIL_ALLOWED_USERS。 否则，只要知道 agent 的邮箱地址，任何人都可以给它发送命令，而 agent 默认拥有终端访问能力。
故障排除
| Problem | Solution |
|---|---|
| 启动时出现 “IMAP connection failed” | 检查 EMAIL_IMAP_HOST 和 EMAIL_IMAP_PORT 是否正确；确认邮箱已启用 IMAP。Gmail 用户需在 Settings → Forwarding and POP/IMAP 中打开。 |
| 启动时出现 “SMTP connection failed” | 检查 EMAIL_SMTP_HOST 和 EMAIL_SMTP_PORT；确认密码正确（Gmail 应使用 App Password）。 |
| 收不到邮件 | 检查 EMAIL_ALLOWED_USERS 是否包含该发件人；同时查看垃圾邮件文件夹，部分服务商会把自动回复判为垃圾邮件。 |
| “Authentication failed” | Gmail 必须使用 App Password，不能用普通密码；且前提是先开启 2FA。 |
| 重复回复 | 确认只运行了一个 gateway 实例；可检查 hermes gateway status。 |
| 响应很慢 | 默认轮询间隔为 15 秒；可改为 EMAIL_POLL_INTERVAL=5 以更快响应，但 IMAP 连接次数也会增加。 |
| 回复没有串在线程里 | 适配器会设置 In-Reply-To 头，但部分邮件客户端（尤其某些 Web 邮箱）对自动消息的线程识别并不稳定。 |
安全
注意
使用专用邮箱账号。 不要用你的个人邮箱，因为 agent 会把密码保存在 .env 中，并且通过 IMAP 拥有完整收件箱访问权限。
- 优先使用 App Password，不要使用主密码（尤其是 Gmail + 2FA）
- 设置
EMAIL_ALLOWED_USERS来限制谁能与 agent 交互 - 密码保存在
~/.hermes/.env中，请妥善保护此文件（例如chmod 600） - 默认情况下，IMAP 使用 SSL（993 端口），SMTP 使用 STARTTLS（587 端口），连接本身是加密的
环境变量参考
| Variable | Required | Default | Description |
|---|---|---|---|
EMAIL_ADDRESS | Yes | — | agent 使用的邮箱地址 |
EMAIL_PASSWORD | Yes | — | 邮箱密码或应用专用密码 |
EMAIL_IMAP_HOST | Yes | — | IMAP 服务器主机（如 imap.gmail.com） |
EMAIL_SMTP_HOST | Yes | — | SMTP 服务器主机（如 smtp.gmail.com） |
EMAIL_IMAP_PORT | No | 993 | IMAP 服务器端口 |
EMAIL_SMTP_PORT | No | 587 | SMTP 服务器端口 |
EMAIL_POLL_INTERVAL | No | 15 | 收件箱轮询间隔（秒） |
EMAIL_ALLOWED_USERS | No | — | 逗号分隔的允许发件人地址 |
EMAIL_HOME_ADDRESS | No | — | cron 任务默认投递目标 |
EMAIL_ALLOW_ALL_USERS | No | false | 允许所有发件人（不推荐） |