跳到主要內容

郵件設置

Hermes 可以使用標準的 IMAP 和 SMTP 協議接收和回覆郵件。向 Agent 的郵箱地址發送郵件，它會以線程方式回覆——無需特殊客戶端或機器人 API。支持 Gmail、Outlook、Yahoo、Fastmail 或任何支持 IMAP/SMTP 的郵件服務商。

無外部依賴

郵件適配器使用 Python 內置的 imaplib、smtplib 和 email 模塊。無需額外安裝包或外部服務。

前提條件​

  • 專用郵箱賬戶：用於你的 Hermes Agent（不要使用個人郵箱）
  • 郵箱賬戶已啟用 IMAP
  • 若使用 Gmail 或其他啟用了雙因素認證（2FA）的服務，需使用應用密碼

Gmail 設置​

  1. 在你的 Google 賬戶中啟用雙因素認證
  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：

# 必填
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      # cron 作業的默認交付目標

第二步：啟動網關​

hermes gateway              # 在前臺運行
hermes gateway install      # 安裝為用戶服務
sudo hermes gateway install --system   # 僅限 Linux：啟動時系統服務

啟動時，適配器會：

  1. 測試 IMAP 和 SMTP 連接
  2. 將收件箱中所有現有郵件標記為“已讀”（僅處理新郵件）
  3. 開始輪詢新郵件

工作原理​

接收消息​

適配器以可配置的間隔（默認 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 使用 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 → 接受任何發件人（請謹慎使用）
注意

始終配置 EMAIL_ALLOWED_USERS。 若未配置，任何知道 Agent 郵箱地址的人都可發送命令。Agent 默認具有終端訪問權限。

故障排除​

問題解決方案
啟動時出現 "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 頭部。某些郵件客戶端（尤其是基於網頁的）可能無法正確對自動化消息進行線程化。

安全性​

注意

請使用專用郵箱賬戶。 不要使用個人郵箱——該 Agent 會將密碼存儲在 .env 文件中，並通過IMAP擁有對收件箱的完全訪問權限。

  • 使用 應用密碼 而非主密碼（Gmail啟用2FA時必需）
  • 設置 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否—定時任務（cron jobs）的默認投遞目標
EMAIL_ALLOW_ALL_USERS否false允許所有發件人（不推薦）