电子邮件

本指南将指导您如何通过 IMAP 和 SMTP 协议将 Hermes Agent 配置为您的电子邮件助手，实现自动收发邮件、智能回复和任务管理。

前置条件

• 已安装并运行 Hermes Agent
• 您的邮箱服务支持 IMAP 和 SMTP（如 Gmail、Outlook、ProtonMail 等）
• 有效的邮箱账户凭据（用户名、密码或应用专用密码）
• 开启邮箱的 IMAP/SMTP 功能
• 了解邮箱的安全设置（如两步验证）

步骤 1：配置邮箱账户信息

获取邮箱凭据

1. 登录您的邮箱管理后台（例如 Gmail）
2. 进入「设置」→「转发和 POP/IMAP」
3. 启用 IMAP
4. 生成应用专用密码（如果启用两步验证）

⚠️ 注意：不要使用主密码，建议使用应用专用密码以增强安全性。

---

步骤 2：在 Hermes Agent 中配置邮箱连接

方法一：通过环境变量配置

在启动 Hermes Agent 时，通过环境变量设置邮箱参数：

export HERMES_EMAIL_IMAP_HOST=imap.gmail.com
export HERMES_EMAIL_IMAP_PORT=993
export HERMES_EMAIL_IMAP_SSL=true
export HERMES_EMAIL_SMTP_HOST=smtp.gmail.com
export HERMES_EMAIL_SMTP_PORT=587
export HERMES_EMAIL_SMTP_SSL=true
export HERMES_EMAIL_USERNAME=your.email@gmail.com
export HERMES_EMAIL_PASSWORD=your-app-password

# 启动 Hermes Agent
hermes-agent --config ./config.yaml

方法二：通过配置文件（推荐）

创建 config.yaml 文件，内容如下：

email:
  imap:
    host: "imap.gmail.com"
    port: 993
    ssl: true
    username: "your.email@gmail.com"
    password: "your-app-password"
    folder: "INBOX"
    check_interval_seconds: 60
  smtp:
    host: "smtp.gmail.com"
    port: 587
    ssl: true
    username: "your.email@gmail.com"
    password: "your-app-password"
    from_email: "your.email@gmail.com"

✅ 推荐使用配置文件方式，便于管理和安全存储。

---

步骤 3：测试邮箱连接

在 Hermes Agent 启动后，检查日志输出是否显示：

✅ Email service connected successfully
📧 IMAP connection established to imap.gmail.com
📤 SMTP connection established to smtp.gmail.com

若出现错误，请检查：

• 网络连接是否正常
• 密码是否正确（特别是应用专用密码）
• 是否开启了 IMAP/SMTP
• 防火墙或安全软件是否阻止连接

---

步骤 4：启用智能邮件处理功能

Hermes Agent 支持以下自动化功能：

功能	描述
📬 自动读取新邮件	定期轮询邮箱，识别未读邮件
💬 智能回复	根据上下文生成自然语言回复
🗂️ 邮件分类	按主题、发件人、关键词自动归类
📅 任务提取	从邮件中提取待办事项并添加到任务列表
🔔 通知提醒	重要邮件触发实时通知

示例：当收到“会议安排”邮件时，Hermes Agent 可自动：

• 提取时间、地点、参会人
• 在日历中创建事件
• 回复确认参加

---

步骤 5：高级配置选项

1. 多邮箱支持

email:
  accounts:
    - name: "personal"
      imap:
        host: "imap.gmail.com"
        username: "personal@gmail.com"
        password: "..."
      smtp:
        host: "smtp.gmail.com"
        username: "personal@gmail.com"
        password: "..."
    - name: "work"
      imap:
        host: "outlook.office365.com"
        username: "work@company.com"
        password: "..."
      smtp:
        host: "smtp.office365.com"
        username: "work@company.com"
        password: "..."

2. 安全增强

• 使用 .env 文件加密敏感信息
• 启用 OAuth2（适用于 Google、Microsoft 等平台）
• 定期轮换应用密码

---

故障排除

问题	解决方案
Authentication failed	检查密码或应用专用密码是否正确
Connection refused	确保 IMAP/SMTP 端口开放（993/587）
SSL handshake failed	检查系统时间是否准确，更新证书
邮件不被读取	检查 folder 字段是否正确，如 INBOX 或 Sent

---

安全提示

• ❌ 不要在代码中硬编码密码
• ✅ 使用环境变量或 .env 文件
• 🔐 启用两步验证 + 应用专用密码
• 📦 定期审计访问权限

---

成功案例

“自从部署 Hermes Agent 作为我的邮件助手，我每天节省了约 1.5 小时。它能自动处理客户咨询、安排会议，并提醒我关键截止日期。”

---

下一步

• 访问 agentskills.io 查看更多 AI 代理技能
• 加入 Discord 社区 获取支持
• 探索 MCP (Model Control Protocol) 实现跨平台集成

---

📌 现在就启动您的智能邮件助手！
只需几分钟，即可让 Hermes Agent 为您处理日常邮件事务。

🔄 保持更新：定期检查 GitHub Releases 以获取最新功能与安全补丁。"

---

邮件设置

Hermes 可通过标准的 IMAP 和 SMTP 协议接收并回复邮件。只需向代理的邮箱发送邮件，它便会以线程方式自动回复——无需特殊客户端或机器人 API。支持 Gmail、Outlook、Yahoo、Fastmail 或任何支持 IMAP/SMTP 的邮件服务商。

无外部依赖

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

---

前提条件

• 专用邮箱账户：为你的 Hermes 代理创建一个独立邮箱（不要使用个人邮箱）
• 已启用 IMAP：在邮箱账户中开启 IMAP 功能
• 应用密码：若使用 Gmail 或其他启用了双因素认证（2FA）的服务，需生成应用密码

Gmail 设置

1. 在 Google 账户中启用双重验证（2FA）
2. 进入 应用密码
3. 创建新的应用密码（选择“邮件”或“其他”）
4. 复制生成的 16 位密码——后续将用它代替常规密码

Outlook / Microsoft 365

1. 访问 安全设置
2. 若未启用，请先开启 2FA
3. 在“其他安全选项”中创建应用密码
4. 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

启动时，适配器将执行以下操作：

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
• 回复内容以纯文本格式（UTF-8）发送

文件附件

代理可在回复中发送文件附件。在响应中包含 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。否则，任何知晓代理邮箱地址的人都可发送指令。默认情况下，该代理拥有终端访问权限。

---

故障排除

问题	解决方案
启动时出现“IMAP 连接失败”	确认 EMAIL_IMAP_HOST 和 EMAIL_IMAP_PORT 正确。确保账户已开启 IMAP 功能。Gmail 用户请进入 设置 → 转发与 POP/IMAP 启用 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 头部。部分邮件客户端（尤其是网页版）可能无法正确处理自动化消息的线程。

---

安全建议

warning

请使用专用邮箱账户。不要使用个人邮箱——代理会将密码存储在 .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 任务的默认投递目标
EMAIL_ALLOW_ALL_USERS	否	false	允许所有发件人（不推荐）