<!-- Source: https://hermesbible.com/docs/user-guide/messaging/email -->

Section: Messaging Platforms · URL: https://hermesbible.com/docs/user-guide/messaging/email

Email 設定

Hermes 可以使用標準的 IMAP 和 SMTP 協議來接收和回覆郵件。寄一封郵件到 agent 的地址，它會在同一個對話串中回覆 — 不需要特殊的用戶端或 Bot API。支援 Gmail、Outlook、Yahoo、Fastmail 或任何支援 IMAP/SMTP 的服務商。

資訊 — 僅使用 Gateway 適配器：無外部依賴

本頁面說明 Email Gateway 適配器，使用 Python 內建的 imaplib、smtplib 和 email 模組。此 Gateway 路徑不需要額外套件或外部服務。

這與內建的 Himalaya email skill 不同。Hermaya email skill 讓 agent 透過終端指令管理郵件，需要外部的 himalaya CLI 以及 Himalaya 設定檔。

---

前置需求

• 一個專用的郵件帳號給你的 Hermes agent 使用（不要用個人郵件）
• 啟用 IMAP 功能的郵件帳號
• 如果使用 Gmail 或其他啟用 2FA 的服務商，需要一個應用程式密碼

Gmail 設定

1. 在你的 Google 帳號上啟用雙重驗證（2FA）
2. 前往 應用程式密碼
3. 建立一個新的應用程式密碼（選擇「Mail」或「Other」）
4. 複製那組 16 字元的密碼 — 你會用它取代一般密碼

Outlook / Microsoft 365

1. 前往 安全性設定
2. 如果尚未啟用 2FA，先將其開啟
3. 在「其他安全性選項」下建立應用程式密碼
4. IMAP 主機：outlook.office365.com，SMTP 主機：smtp.office365.com

其他服務商

大多數郵件服務商都支援 IMAP/SMTP。請查看你的服務商文件確認以下資訊：

• IMAP 主機和連接埠（通常是 SSL 連接埠 993）
• SMTP 主機和連接埠（通常是 STARTTLS 連接埠 587）
• 是否需要應用程式密碼

---

步驟一：設定 Hermes

最簡單的方式：

hermes gateway setup

從平台選單中選擇 Email。設定精靈會要求你輸入郵件地址、密碼、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      # 排程工作的預設傳送目標

---

步驟二：啟動 Gateway

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

啟用後，附件和內嵌元件會在解碼承載內容前被跳過。郵件正文仍然會正常處理。

---

存取控制

Email 存取遵循所有其他 Hermes 平台相同的模式：

1. 設定了 EMAIL_ALLOWED_USERS → 只會處理來自這些地址的郵件
2. 未設定允許清單 → 未知寄件者會收到一組配對碼
3. EMAIL_ALLOW_ALL_USERS=true → 接受任何寄件者（請謹慎使用）

警告

請務必設定 EMAIL_ALLOWED_USERS。 如果沒有設定，任何知道 agent 郵件地址的人都可以傳送指令。Agent 預設具有終端存取權限。

---

疑難排解

---

安全性

警告

請使用專用郵件帳號。 不要使用個人郵件 — agent 會將密碼儲存在 .env 中，並透過 IMAP 擁有完整的收件匣存取權限。

• 使用應用程式密碼而非主要密碼（Gmail 啟用 2FA 時必須如此）
• 設定 EMAIL_ALLOWED_USERS 以限制誰可以與 agent 互動
• 密碼儲存在 ~/.hermes/.env 中 — 請保護這個檔案（chmod 600）
• IMAP 預設使用 SSL（連接埠 993），SMTP 預設使用 STARTTLS（連接埠 587）— 連線均為加密傳輸

---

環境變數參考

---

---

SMS（Twilio）