🏠 Главная › User Guide › wecom

sidebar_position: 14 title: "WeCom (Enterprise WeChat)" description: "Connect Hermes Agent to WeCom via the AI Bot WebSocket gateway" lang: ru

WeCom (корпоративный WeChat)

Подключите Hermes к WeCom (企业微信), корпоративной платформе обмена сообщениями Tencent. Адаптер использует шлюз WeCom AI Bot WebSocket для двунаправленной связи в реальном времени — не требуется общедоступная конечная точка или веб-перехватчик.

Предварительные условия

Настройка

Шаг 1. Создайте ИИ-бота

Рекомендуется: сканирование и создание (одна команда)

hermes gateway setup

Выберите WeCom и отсканируйте QR-код с помощью мобильного приложения WeCom. Hermes автоматически создаст бот-приложение с правильными разрешениями и сохранит учетные данные.

Мастер установки выполнит следующие действия: 1. Отобразите QR-код в своем терминале. 2. Подождите, пока вы отсканируете его с помощью мобильного приложения WeCom. 3. Автоматически получить идентификатор и секрет бота. 4. Проведет вас через настройку контроля доступа.

Альтернатива: ручная настройка

Если сканирование для создания недоступно, мастер возвращается к ручному вводу:

  1. Войдите в Консоль администратора WeCom
  2. Перейдите к Приложения → Создать приложение → AI Bot.
  3. Настройте имя и описание бота.
  4. Скопируйте Идентификатор бота и Секрет со страницы учетных данных.
  5. Запустите hermes gateway setup, выберите WeCom и введите учетные данные при появлении запроса.

:::предупреждение Держите секрет бота в тайне. Любой, у кого он есть, может выдать себя за вашего бота.

Шаг 2. Настройте Гермес

Вариант A: Интерактивная настройка (рекомендуется)

hermes gateway setup

Выберите WeCom и следуйте инструкциям. Мастер проведет вас через: - Учетные данные бота (через QR-сканирование или ввод вручную) - Настройки контроля доступа (белый список, режим сопряжения или открытый доступ) - Домашний канал для уведомлений

Вариант Б: Настройка вручную

Добавьте следующее в ~/.hermes/.env:

WECOM_BOT_ID=your-bot-id
WECOM_SECRET=your-secret

# Optional: restrict access
WECOM_ALLOWED_USERS=user_id_1,user_id_2

# Optional: home channel for cron/notifications
WECOM_HOME_CHANNEL=chat_id

Шаг 3: Запустите шлюз

hermes gateway

Особенности

Параметры конфигурации

Установите их в config.yaml под platforms.wecom.extra:

Ключ По умолчанию Описание
bot_id — Идентификатор бота WeCom AI (обязательно)
secret — Секрет WeCom AI Bot (обязательно)
websocket_url wss://openws.work.weixin.qq.com URL-адрес шлюза WebSocket
dm_policy open Доступ в ЛС: open, allowlist, disabled, pairing
group_policy open Групповой доступ: open, allowlist, disabled
allow_from [] Идентификаторы пользователей, разрешенные для личных сообщений (когда dm_policy=allowlist)
group_allow_from [] Идентификаторы групп разрешены (когда group_policy=allowlist)
groups {} Групповая конфигурация (см. ниже)

Политики доступа

Политика DM

Определяет, кто может отправлять прямые сообщения боту:

Значение Поведение
open Любой может отправить сообщение боту (по умолчанию)
allowlist Только идентификаторы пользователей в allow_from могут отправлять сообщения
disabled Все DM игнорируются
pairing Режим сопряжения (для первоначальной настройки) 
WECOM_DM_POLICY=allowlist

Групповая политика

Определяет, в каких группах отвечает бот:

Значение Поведение
open Бот отвечает во всех группах (по умолчанию)
allowlist Бот отвечает только на группы с идентификаторами, указанными в group_allow_from
disabled Все групповые сообщения игнорируются 
WECOM_GROUP_POLICY=allowlist

Белые списки отправителей для каждой группы

Для более детального контроля вы можете ограничить пользователей, которым разрешено взаимодействовать с ботом в определенных группах. Это настраивается в config.yaml:

platforms:
  wecom:
    enabled: true
    extra:
      bot_id: "your-bot-id"
      secret: "your-secret"
      group_policy: "allowlist"
      group_allow_from:
        - "group_id_1"
        - "group_id_2"
      groups:
        group_id_1:
          allow_from:
            - "user_alice"
            - "user_bob"
        group_id_2:
          allow_from:
            - "user_charlie"
        "*":
          allow_from:
            - "user_admin"

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

  1. Элементы управления group_policy и group_allow_from определяют, разрешена ли группа вообще.
  2. Если группа проходит проверку верхнего уровня, список groups.<group_id>.allow_from (если присутствует) дополнительно ограничивает отправителей в этой группе, которые могут взаимодействовать с ботом.
  3. Запись группы "*" с подстановочным знаком используется по умолчанию для групп, не перечисленных явно.
  4. Записи белого списка поддерживают подстановочный знак *, позволяющий разрешить всем пользователям, а записи не чувствительны к регистру.
  5. Записи могут дополнительно использовать формат префикса wecom:user: или wecom:group: — префикс удаляется автоматически.

Если для группы не настроен allow_from, все пользователи в этой группе разрешены (при условии, что сама группа проходит проверку политики верхнего уровня).

Медиа-поддержка

Входящий (прием)

Адаптер получает мультимедийные вложения от пользователей и локально кэширует их для обработки агентом:

Тип Как это решается
Изображения Скачивается и кэшируется локально. Поддерживает изображения как на основе URL, так и в кодировке Base64.
Файлы Скачал и закешировал. Имя файла сохраняется из исходного сообщения.
Голос Транскрипция текста голосового сообщения извлекается, если доступна.
Смешанные сообщения Сообщения WeCom смешанного типа (текст + изображения) анализируются и извлекаются все компоненты.

Цитируемые сообщения. Медиафайлы из цитируемых (ответных) сообщений также извлекаются, поэтому агент имеет контекст о том, на что отвечает пользователь.

Расшифровка медиафайлов с шифрованием AES

WeCom шифрует некоторые входящие мультимедийные вложения с помощью AES-256-CBC. Адаптер обрабатывает это автоматически:

Никакой настройки не требуется — расшифровка происходит прозрачно при получении зашифрованного носителя.

Исходящие (отправка)

Метод Что он отправляет Ограничение размера
send Текстовые сообщения с уценкой 4000 символов
send_image / send_image_file Собственные графические сообщения 10 МБ
send_document Вложения файлов 20 МБ
send_voice Голосовые сообщения (формат AMR только для собственного голоса) 2 МБ
send_video Видео сообщения 10 МБ

Частная загрузка. Файлы загружаются частями по 512 КБ по трехэтапному протоколу (инициализация → фрагменты → завершение). Адаптер обрабатывает это автоматически.

Автоматический переход на более раннюю версию. Если размер носителя превышает максимальный размер исходного типа, но не превышает абсолютного предела в 20 МБ, он автоматически отправляется в виде вложенного файла:

Файлы, размер которых превышает абсолютный лимит в 20 МБ, отклоняются с отправкой в чат информационного сообщения.

Ответы потока в режиме ответа

Когда бот получает сообщение через обратный вызов WeCom, адаптер запоминает идентификатор входящего запроса. Если ответ отправляется, когда контекст запроса все еще активен, адаптер использует режим ответа WeCom (aibot_respond_msg) с потоковой передачей для прямой корреляции ответа с входящим сообщением. Это обеспечивает более естественный диалог в клиенте WeCom.

Если контекст входящего запроса истек или недоступен, адаптер возвращается к упреждающей отправке сообщений через aibot_send_msg.

Режим ответа также работает для мультимедиа: загруженные медиафайлы можно отправить в качестве ответа на исходное сообщение.

Подключение и переподключение

Адаптер поддерживает постоянное соединение WebSocket со шлюзом WeCom по адресу wss://openws.work.weixin.qq.com.

Жизненный цикл соединения

  1. Подключиться: открывает соединение WebSocket и отправляет кадр аутентификации aibot_subscribe с bot_id и секретным ключом.
  2. Heartbeat: каждые 30 секунд отправляет пинг-фреймы на уровне приложения, чтобы поддерживать соединение.
  3. Прослушивание: непрерывно считывает входящие кадры и отправляет обратные вызовы сообщений.

Поведение при повторном подключении

При потере соединения адаптер использует экспоненциальную задержку для повторного подключения:

Попытка Задержка
1-я повторная попытка 2 секунды
2-я повторная попытка 5 секунд
3-я повторная попытка 10 секунд
4-я повторная попытка 30 секунд
5-я+ повтор 60 секунд

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

Дедупликация

Входящие сообщения дедуплицируются с использованием идентификаторов сообщений с 5-минутным окном и максимальным кэшем в 1000 записей. Это предотвращает двойную обработку сообщений во время повторного подключения или сбоев в сети.

Все переменные среды

Переменная Требуется По умолчанию Описание
WECOM_BOT_ID ✅ — Идентификатор бота WeCom AI
WECOM_SECRET ✅ — Секрет WeCom AI Bot
WECOM_ALLOWED_USERS — (пусто) Идентификаторы пользователей, разделенные запятыми, для белого списка на уровне шлюза
WECOM_HOME_CHANNEL — — Идентификатор чата для вывода cron/уведомлений
WECOM_WEBSOCKET_URL — wss://openws.work.weixin.qq.com URL-адрес шлюза WebSocket
WECOM_DM_POLICY — open Политика доступа к личным сообщениям
WECOM_GROUP_POLICY — open Политика группового доступа

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

Проблема Исправить
WECOM_BOT_ID and WECOM_SECRET are required Установите обе переменные окружения или настройте в мастере установки
WeCom startup failed: aiohttp not installed Установите aiohttp: pip install aiohttp
WeCom startup failed: httpx not installed Установите httpx: pip install httpx
invalid secret (errcode=40013) Убедитесь, что секрет соответствует учетным данным вашего бота
Timed out waiting for subscribe acknowledgement Проверьте сетевое подключение к openws.work.weixin.qq.com
Бот не отвечает в группах Проверьте настройку group_policy и убедитесь, что идентификатор группы указан в group_allow_from
Бот игнорирует определенных пользователей в группе Проверьте списки allow_from для каждой группы в разделе конфигурации groups
Расшифровка мультимедиа не удалась Установите cryptography: pip install cryptography
cryptography is required for WeCom media decryption Входящие медиафайлы шифруются с помощью AES. Установить: pip install cryptography
Голосовые сообщения, отправленные в виде файлов WeCom поддерживает только формат AMR для собственного голоса. Другие форматы автоматически преобразуются в файл.
File too large ошибка WeCom имеет абсолютный лимит в 20 МБ на загрузку всех файлов. Сжать или разделить файл.
Изображения, отправленные в виде файлов Изображения размером > 10 МБ превышают собственный лимит изображений и автоматически преобразуются в вложенные файлы.
Timeout sending message to WeCom Возможно, WebSocket отключен. Проверьте журналы на наличие сообщений о переподключении.
WeCom websocket closed during authentication Проблема с сетью или неправильные учетные данные. Проверьте bot_id и секрет.