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

Команды установки Python-зависимостей на этой странице рассчитаны на чекаут исходников, подготовленный через PM. После изменения зависимостей заново активируйте чекаут и перезапустите Hermes.

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

См. также: WeCom Callback — настройка входящего вебхука.

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

• Организационный аккаунт WeCom
• AI Bot, созданный в админ-консоли WeCom
• Bot ID и Secret со страницы учётных данных бота
• Python-пакеты: aiohttp и httpx

Настройка

Шаг 1. Создайте AI Bot

Рекомендуемый способ: создание по QR-коду (одна команда)

hermes gateway setup

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

Мастер настройки выполнит следующее:

1. Покажет QR-код прямо в терминале
2. Подождёт, пока вы отсканируете его приложением WeCom
3. Автоматически получит Bot ID и Secret
4. Проведёт вас через настройку контроля доступа

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

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

1. Войдите в админ-консоль WeCom
2. Перейдите в Applications → Create Application → AI Bot
3. Задайте имя и описание бота
4. Скопируйте Bot ID и Secret со страницы учётных данных
5. Запустите hermes gateway setup, выберите WeCom и введите учётные данные по запросу

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

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

hermes gateway setup

Выберите WeCom и следуйте подсказкам. Мастер проведёт вас через:

• Учётные данные бота (по QR-коду или вручную)
• Параметры контроля доступа (список разрешений, режим сопряжения или открытый доступ)
• Домашний канал для уведомлений

Вариант B: ручная конфигурация

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

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

# Опционально: ограничить доступ
WECOM_ALLOWED_USERS=user_id_1,user_id_2

# Опционально: домашний канал для cron/уведомлений
WECOM_HOME_CHANNEL=chat_id

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

hermes gateway

Возможности

• Транспорт WebSocket — постоянное соединение, публичный эндпоинт не нужен
• Личные и групповые сообщения — настраиваемые политики доступа
• Списки разрешённых отправителей для каждой группы — точный контроль над тем, кто общается с ботом в конкретной группе
• Поддержка медиа — загрузка и скачивание изображений, файлов, голоса и видео
• Медиа с AES-шифрованием — входящие вложения расшифровываются автоматически
• Контекст цитирования — сохраняется привязка ответа к ветке
• Рендеринг Markdown — форматированные ответы
• Корреляция ответов — ответ привязывается к контексту входящего сообщения
• Автопереподключение — экспоненциальная выдержка при обрывах связи

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

Задаются в config.yaml в секции platforms.wecom.extra:

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

Политика личных сообщений

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

WECOM_DM_POLICY=allowlist

Политика групп

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

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, разрешены все её участники (при условии, что сама группа прошла проверку политики верхнего уровня).

Поддержка медиа

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

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

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

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

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

• Когда у входящего медиа есть поле aeskey, адаптер скачивает зашифрованные байты и расшифровывает их по AES-256-CBC с дополнением PKCS#7.
• Ключ AES — это значение поля aeskey, раскодированное из base64 (должно быть ровно 32 байта).
• IV берётся из первых 16 байт ключа.
• Понадобится Python-пакет cryptography (hermes pm repair).

Настраивать ничего не нужно: расшифровка происходит прозрачно при получении зашифрованного медиа.

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

Загрузка по частям: файлы загружаются кусками по 512 КБ через трёхэтапный протокол (init → chunks → finish). Адаптер делает это сам.

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

• Изображения > 10 МБ → отправляются файлом
• Видео > 10 МБ → отправляются файлом
• Голос > 2 МБ → отправляется файлом
• Аудио не в AMR → отправляется файлом (для нативного голоса WeCom поддерживает только AMR)

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

Ответы в режиме reply

Получив сообщение через WeCom callback, адаптер запоминает ID входящего запроса. Если ответ отправляется, пока контекст запроса ещё активен, адаптер использует режим reply WeCom (aibot_respond_msg) и привязывает ответ напрямую к входящему сообщению. В клиенте WeCom разговор от этого выглядит естественнее.

Когда активен нативный reply-стрим, ответ передаётся постепенно через кадры reply-режима msgtype: "stream". Если контекст входящего запроса истёк, недоступен или кадр стрима не прошёл, адаптер переключается на проактивную отправку через aibot_send_msg.

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

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

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

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

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

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

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

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

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

Входящие сообщения дедуплицируются по ID сообщений с окном в 5 минут и кешем не более чем на 1000 записей. Так одно и то же сообщение не обрабатывается дважды во время переподключения или сетевых сбоев.

Все переменные окружения

Решение проблем