Перейти к основному содержимому

Настройка Email

VibeOS может получать и отправлять электронные письма, используя стандартные протоколы IMAP и SMTP. Отправьте письмо на адрес агента, и он ответит в той же цепочке — никакого специального клиента или API бота не требуется. Работает с Gmail, Outlook, Yahoo, Fastmail или любым провайдером, поддерживающим IMAP/SMTP.

Только адаптер шлюза: без внешних зависимостей

Эта страница описывает адаптер шлюза Email, который использует встроенные модули Python imaplib, smtplib и email. Для этого пути шлюза не требуются дополнительные пакеты или внешние сервисы.

Это отличается от встроенного навыка Himalaya email, который позволяет агенту управлять электронной почтой через терминальные команды и требует внешнего CLI himalaya и файла конфигурации Himalaya.

Сценарий использованияЧто настраиватьВнешняя зависимость
Разрешить людям отправлять письма агенту VibeOS и получать ответыАдаптер шлюза Email на этой страницеНичего, кроме учетной записи IMAP/SMTP
Разрешить агенту просматривать, составлять, перемещать и управлять сообщениями почтового ящика с помощью терминальных инструментовНавык Himalaya emailCLI himalaya и ~/.config/himalaya/config.toml

Предварительные требования​

  • Выделенная учетная запись электронной почты для вашего агента VibeOS (не используйте личную почту)
  • IMAP включен в учетной записи электронной почты
  • Пароль приложения, если используется Gmail или другой провайдер с двухфакторной аутентификацией

Настройка Gmail​

  1. Включите двухфакторную аутентификацию в своей учетной записи Google
  2. Перейдите в Пароли приложений
  3. Создайте новый пароль приложения (выберите «Почта» или «Другое»)
  4. Скопируйте 16-символьный пароль — вы будете использовать его вместо обычного пароля

Outlook / Microsoft 365​

  1. Перейдите в Настройки безопасности
  2. Включите двухфакторную аутентификацию, если она еще не активна
  3. Создайте пароль приложения в разделе «Дополнительные параметры безопасности»
  4. IMAP-хост: outlook.office365.com, SMTP-хост: smtp.office365.com

Другие провайдеры​

Большинство почтовых провайдеров поддерживают IMAP/SMTP. Проверьте документацию вашего провайдера для получения информации о:

  • IMAP-хосте и порте (обычно порт 993 с SSL)
  • SMTP-хосте и порте (обычно порт 587 с STARTTLS)
  • Необходимости использования паролей приложений

Шаг 1: Настройка VibeOS​

Самый простой способ:

vibeos gateway setup

Выберите Email в меню платформы. Мастер запросит ваш адрес электронной почты, пароль, IMAP/SMTP-хосты и разрешенных отправителей.

Ручная настройка​

Добавьте в ~/.vibeos/.env:

# Обязательные
EMAIL_ADDRESS=vibeos@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

Шаг 2: Запуск шлюза​

vibeos gateway              # Запуск в фоновом режиме
vibeos gateway install      # Установка как пользовательский сервис
sudo vibeos gateway install --system   # Только Linux: системный сервис при загрузке

При запуске адаптер:

  1. Проверяет соединения IMAP и SMTP
  2. Помечает все существующие сообщения во входящих как «просмотренные» (обрабатывает только новые письма)
  3. Начинает опрос на наличие новых сообщений

Как это работает​

Получение сообщений​

Адаптер опрашивает папку входящих IMAP на наличие НЕПРОЧИТАННЫХ сообщений с настраиваемым интервалом (по умолчанию: 15 секунд). Для каждого нового письма:

  • Строка темы включается как контекст (например, [Subject: Deploy to production])
  • Ответные письма (тема начинается с Re:) пропускают префикс темы — контекст цепочки уже установлен
  • Вложения кэшируются локально:
    • Изображения (JPEG, PNG, GIF, WebP) → доступны для инструмента vision
    • Документы (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 генерируется с доменом агента
  • Ответы отправляются в виде обычного текста (UTF-8)

Вложения файлов​

Агент может отправлять вложения файлов в ответах. Включите MEDIA:/path/to/file в ответ, и файл будет прикреплен к исходящему письму.

Пропуск вложений​

Чтобы игнорировать все входящие вложения (для защиты от вредоносных программ или экономии трафика), добавьте в config.yaml:

platforms:
  email:
    skip_attachments: true

При включении этой опции вложения и встроенные части пропускаются перед декодированием полезной нагрузки. Текст письма обрабатывается как обычно.

Контроль доступа​

Доступ по электронной почте по умолчанию более строгий, чем в чат-платформах:

  1. EMAIL_ALLOWED_USERS установлен → обрабатываются только письма с этих адресов
  2. Белый список не задан → неизвестные отправители игнорируются без уведомления
  3. EMAIL_ALLOW_ALL_USERS=true → принимаются любые отправители (используйте с осторожностью)
  4. platforms.email.unauthorized_dm_behavior: pair → неизвестные отправители получают код для сопряжения
предупреждение

Используйте выделенный почтовый ящик и настройте EMAIL_ALLOWED_USERS для нормальной работы. Сопряжение по электронной почте является опциональным, потому что общие почтовые ящики часто содержат несвязанные непрочитанные сообщения, и VibeOS не должен отвечать на эти контакты по умолчанию.

Устранение неполадок​

ПроблемаРешение
«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 включает адрес отправителя. Проверьте папку со спамом — некоторые провайдеры помечают автоматические ответы.
«Authentication failed»Для Gmail необходимо использовать пароль приложения, а не обычный пароль. Убедитесь, что двухфакторная аутентификация включена.
Дублирующиеся ответыУбедитесь, что запущен только один экземпляр шлюза. Проверьте vibeos gateway status.
Медленный ответИнтервал опроса по умолчанию составляет 15 секунд. Уменьшите с помощью EMAIL_POLL_INTERVAL=5 для более быстрого ответа (но больше IMAP-соединений).
Ответы не группируются в цепочкиАдаптер использует заголовки In-Reply-To. Некоторые почтовые клиенты (особенно веб-версии) могут неправильно группировать автоматические сообщения.

Безопасность​

предупреждение

Используйте выделенную учетную запись электронной почты. Не используйте личную почту — агент хранит пароль в .env и имеет полный доступ к почтовому ящику через IMAP.

  • Используйте пароли приложений вместо основного пароля (требуется для Gmail с двухфакторной аутентификацией)
  • Установите EMAIL_ALLOWED_USERS, чтобы ограничить круг лиц, которые могут взаимодействовать с агентом
  • Пароль хранится в ~/.vibeos/.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Разрешить всех отправителей (не рекомендуется)