On this page
Hermes может получать и отправлять электронные письма, используя стандартные протоколы IMAP и SMTP. Отправьте письмо на адрес агента — и он ответит в той же переписке; никакого специального клиента или Bot API не требуется. Работает с Gmail, Outlook, Yahoo, Fastmail и любым провайдером, поддерживающим IMAP/SMTP.
No External Dependencies
Адаптер электронной почты использует встроенные модули Python: imaplib, smtplib и email. Никаких дополнительных пакетов или внешних сервисов не требуется.
Предварительные требования¶
- Отдельный почтовый аккаунт для вашего агента Hermes (не используйте личную почту)
- IMAP включён в настройках почтового аккаунта
- Пароль приложения в случае использования Gmail или другого провайдера с двухфакторной аутентификацией
Настройка Gmail¶
- Включите двухфакторную аутентификацию в вашем аккаунте Google
- Перейдите в Пароли приложений
- Создайте новый пароль приложения (выберите «Почта» или «Другое»)
- Скопируйте 16-символьный пароль — вы будете использовать его вместо обычного пароля
Outlook / Microsoft 365¶
- Перейдите в Параметры безопасности
- Включите двухфакторную аутентификацию, если ещё не включена
- Создайте пароль приложения в разделе «Дополнительные параметры безопасности»
- IMAP-хост:
outlook.office365.com, SMTP-хост:smtp.office365.com
Другие провайдеры¶
Большинство почтовых провайдеров поддерживают IMAP/SMTP. Уточните в документации вашего провайдера: * IMAP-хост и порт (обычно порт 993 с SSL) * SMTP-хост и порт (обычно порт 587 с STARTTLS) * Требуются ли пароли приложений
Шаг 1: Настройте Hermes¶
Самый простой способ: [code] hermes gateway setup
[/code] Выберите Email в меню платформ. Мастер запросит ваш email-адрес, пароль, IMAP/SMTP-хосты и список отправителей, которым разрешено взаимодействие.
Ручная настройка¶
Добавьте в ~/.hermes/.env:
[code]
# Обязательные
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-задач
[/code]
Шаг 2: Запустите шлюз¶
[code]
hermes gateway # Запуск в интерактивном режиме
hermes gateway install # Установка как пользовательский сервис
sudo hermes gateway install --system # Только Linux: системный сервис автозагрузки
[/code] При запуске адаптер: 1. Проверяет подключения IMAP и SMTP 2. Помечает все существующие сообщения во входящих как «прочитанные» (обрабатываются только новые письма) 3. Начинает опрос на предмет новых сообщений
Как это работает¶
Получение сообщений¶
Адаптер опрашивает папку «Входящие» IMAP на наличие НЕПРОЧИТАННЫХ сообщений с настраиваемым интервалом (по умолчанию: 15 секунд). Для каждого нового письма:
* Тема письма включается как контекст (например, [Subject: Deploy to production])
* Ответные письма (тема начинается с Re:) пропускают префикс темы — контекст переписки уже установлен
* Вложения кэшируются локально:
* Изображения (JPEG, PNG, GIF, WebP) → доступны инструменту vision
* Документы (PDF, ZIP и т.д.) → доступны для работы с файлами
* Письма только в HTML очищаются от тегов для извлечения текста
* Собственные сообщения отфильтровываются для предотвращения циклов ответов
* Автоматические отправители и no-reply молча игнорируются — 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:
[code]
platforms:
email:
skip_attachments: true
[/code] При включении этой настройки вложения и встроенные части пропускаются до декодирования содержимого. Текст письма обрабатывается как обычно.
Контроль доступа¶
Доступ по электронной почте следует тому же принципу, что и все остальные платформы Hermes:
1. EMAIL_ALLOWED_USERS указан → обрабатываются только письма с этих адресов
2. Белый список не задан → неизвестные отправители получают код для привязки
3. EMAIL_ALLOW_ALL_USERS=true → принимаются письма от любого отправителя (используйте с осторожностью)
warning
Всегда настраивайтеEMAIL_ALLOWED_USERS. Без этого любой, кто знает email-адрес агента, сможет отправлять ему команды. По умолчанию агент имеет доступ к терминалу.
Устранение неполадок¶
| Проблема | Решение |
|---|---|
| «IMAP connection failed» при запуске | Проверьте EMAIL_IMAP_HOST и EMAIL_IMAP_PORT. Убедитесь, что IMAP включён в настройках аккаунта. Для Gmail включите его в Настройках → Пересылка и POP/IMAP. |
| «SMTP connection failed» при запуске | Проверьте EMAIL_SMTP_HOST и EMAIL_SMTP_PORT. Убедитесь, что пароль верен (для Gmail используйте пароль приложения). |
| Сообщения не приходят | Проверьте, что EMAIL_ALLOWED_USERS включает email отправителя. Проверьте папку «Спам» — некоторые провайдеры помечают автоматические ответы как спам. |
| «Authentication failed» | Для Gmail необходимо использовать пароль приложения, а не основной пароль. Убедитесь, что двухфакторная аутентификация включена. |
| Дублирующиеся ответы | Убедитесь, что запущен только один экземпляр шлюза. Проверьте hermes gateway status. |
| Медленный ответ | Интервал опроса по умолчанию — 15 секунд. Уменьшите с помощью EMAIL_POLL_INTERVAL=5 для более быстрого ответа (но это увеличит количество IMAP-подключений). |
| Ответы не формируют цепочку | Адаптер использует заголовки In-Reply-To. Некоторые почтовые клиенты (особенно веб-версии) могут некорректно группировать автоматические сообщения в цепочки. |
| * * * | |
| ## Безопасность | |
| warning | |
Используйте отдельный почтовый аккаунт. Не используйте личную почту — агент хранит пароль в .env и имеет полный доступ к папке «Входящие» через IMAP. |
|
| * Используйте пароли приложений вместо основного пароля (обязательно для Gmail с двухфакторной аутентификацией) | |
* Установите EMAIL_ALLOWED_USERS, чтобы ограничить круг лиц, взаимодействующих с агентом |
|
* Пароль хранится в ~/.hermes/.env — защитите этот файл (chmod 600) |
|
| * IMAP использует SSL (порт 993), а SMTP — STARTTLS (порт 587) по умолчанию — соединения шифруются |
Справочник переменных окружения¶
| Переменная | Обязательная | По умолчанию | Описание |
|---|---|---|---|
EMAIL_ADDRESS |
Да | — | Email-адрес агента |
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 |
Разрешить всех отправителей (не рекомендуется) |
| * Предварительные требования | |||
| * Настройка Gmail | |||
| * Outlook / Microsoft 365 | |||
| * Другие провайдеры | |||
| * Шаг 1: Настройте Hermes | |||
| * Ручная настройка | |||
| * Шаг 2: Запустите шлюз | |||
| * Как это работает | |||
| * Получение сообщений | |||
| * Отправка ответов | |||
| * Вложения файлов | |||
| * Пропуск вложений | |||
| * Контроль доступа | |||
| * Устранение неполадок | |||
| * Безопасность | |||
| * Справочник переменных окружения |