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

sidebar_position: 15 title: "Weixin (WeChat)" description: "Connect Hermes Agent to personal WeChat accounts via the iLink Bot API" lang: ru

Вейсинь (WeChat)

Подключите Hermes к WeChat (微信), платформе персональных сообщений Tencent. Адаптер использует iLink Bot API от Tencent для личных учетных записей WeChat — это отличается от WeCom (Enterprise WeChat). Сообщения доставляются посредством длительного опроса, поэтому не требуется общедоступная конечная точка или веб-перехватчик.

:::информация Этот адаптер предназначен для личных учетных записей WeChat (微信). Если вам нужен корпоративный/корпоративный WeChat, вместо этого воспользуйтесь адаптером WeCom.

:::предупреждение об идентификации бота iLink — обычные группы WeChat могут не работать Вход с помощью QR подключает Hermes к идентификатору бота iLink (например, a5ace6fd482e@im.bot), а не к обычной личной учетной записи WeChat, полностью поддерживающей сценарии. Последствия:

На практике в большинстве развертываний надежно работают только DM с ботом iLink. Если групповая доставка не работает после настройки, ограничение существует на стороне iLink, а не в Hermes. Шлюз регистрирует WARNING при запуске всякий раз, когда для WEIXIN_GROUP_POLICY установлено любое значение, кроме disabled.

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

Установите необходимые зависимости:

pip install aiohttp cryptography
# Optional: for terminal QR code display
pip install hermes-agent[messaging]

Настройка

1. Запустите мастер установки.

Самый простой способ подключить свою учетную запись WeChat — через интерактивную настройку:

hermes gateway setup

При появлении запроса выберите Weixin. Мастер:

  1. Запросите QR-код у iLink Bot API.
  2. Отобразите QR-код на своем терминале (или укажите URL-адрес).
  3. Подождите, пока вы отсканируете QR-код с помощью мобильного приложения WeChat.
  4. Предложить подтвердить вход на телефоне.
  5. Автоматически сохраните учетные данные в ~/.hermes/weixin/accounts/.

После подтверждения вы увидите сообщение типа:

微信连接成功，account_id=your-account-id

Мастер сохраняет account_id, token и base_url, поэтому вам не нужно настраивать их вручную.

2. Настройка переменных среды

После первоначального входа в систему QR установите как минимум идентификатор учетной записи в ~/.hermes/.env:

WEIXIN_ACCOUNT_ID=your-account-id

# Optional: override the token (normally auto-saved from QR login)
# WEIXIN_TOKEN=your-bot-token

# Optional: restrict access
WEIXIN_DM_POLICY=open
WEIXIN_ALLOWED_USERS=user_id_1,user_id_2

# Optional: restore legacy multiline splitting behavior
# WEIXIN_SPLIT_MULTILINE_MESSAGES=true

# Optional: home channel for cron/notifications
WEIXIN_HOME_CHANNEL=chat_id
WEIXIN_HOME_CHANNEL_NAME=Home

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

hermes gateway

Адаптер восстановит сохраненные учетные данные, подключится к API iLink и начнет длительный опрос сообщений.

Особенности

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

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

Ключ По умолчанию Описание
account_id — Идентификатор учетной записи бота iLink (обязательно)
token — Токен iLink Bot (обязательно, автоматически сохраняется при входе в QR)
base_url https://ilinkai.weixin.qq.com iLink API base URL
cdn_base_url https://novac2c.cdn.weixin.qq.com/c2c Базовый URL-адрес CDN для передачи мультимедиа
dm_policy open Доступ в ЛС: open, allowlist, disabled, pairing
group_policy disabled Групповой доступ: open, allowlist, disabled
allow_from [] Идентификаторы пользователей, разрешенные для личных сообщений (когда dm_policy=allowlist)
group_allow_from [] Идентификаторы групп разрешены (когда group_policy=allowlist)
split_multiline_messages false При true многострочные ответы разделяются на несколько сообщений чата (устаревшее поведение). При false сохраняйте многострочные ответы как одно сообщение, если они не превышают ограничение по длине.

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

Политика DM

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

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

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

Определяет, в каких группах реагирует бот когда iLink доставляет групповые события для подключенного удостоверения. Для идентификаторов бота iLink с QR-входом (например, ...@im.bot) групповые события обычно не доставляются вообще, поэтому эта политика может не иметь эффекта — см. предупреждение об ограничении бота iLink в верхней части страницы.

Значение Поведение
open Бот отвечает во всех группах (если проводятся мероприятия)
allowlist Бот отвечает только на группы с идентификаторами, указанными в group_allow_from (если события доставляются)
disabled Все групповые сообщения игнорируются (по умолчанию) 
WEIXIN_GROUP_POLICY=allowlist
# NOTE: this is a comma-separated list of group chat IDs, NOT member user IDs,
# despite the variable name containing "USERS". Keep this in mind when configuring.
WEIXIN_GROUP_ALLOWED_USERS=group_id_1,group_id_2

:::примечание Групповая политика по умолчанию для Weixin — disabled (в отличие от WeCom, где по умолчанию используется open). Это сделано намеренно: личные учетные записи WeChat могут входить во многие группы, а идентификаторы ботов iLink обычно вообще не могут получать обычные групповые сообщения WeChat. Шлюз регистрирует WARNING при запуске, если вы установили для WEIXIN_GROUP_POLICY любое значение, кроме disabled.

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

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

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

Тип Как это решается
Изображения Загружено, расшифровано AES и кэшировано в формате JPEG.
Видео Загружено, расшифровано AES и кэшировано как MP4.
Файлы Скачивается, расшифровывается по AES и кэшируется. Исходное имя файла сохраняется.
Голос Если доступна текстовая транскрипция, она извлекается как текст. В противном случае аудио (формат SILK) загружается и кэшируется.

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

CDN с шифрованием AES-128-ECB

Медиа-файлы WeChat передаются через зашифрованную CDN. Адаптер обрабатывает это прозрачно:

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

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

Метод Что он отправляет
send Текстовые сообщения в формате Markdown
send_image / send_image_file Собственные графические сообщения (через загрузку CDN)
send_document Вложения файлов (через загрузку CDN)
send_video Видеосообщения (через загрузку CDN)

Все исходящие медиафайлы проходят через зашифрованный поток загрузки CDN:

  1. Сгенерируйте случайный ключ AES-128.
  2. Зашифруйте файл с заполнением AES-128-ECB + PKCS#7.
  3. Запросите URL-адрес загрузки у iLink API (getuploadurl)
  4. Загрузите зашифрованный текст в CDN.
  5. Отправьте сообщение с зашифрованной ссылкой на медиафайл.

Сохранение токена контекста

API-интерфейс iLink Bot требует, чтобы context_token возвращался с каждым исходящим сообщением для данного узла. Адаптер поддерживает хранилище контекстных токенов на диске:

Это обеспечивает непрерывность ответа даже после перезапуска шлюза.

Форматирование уценки

Клиенты WeChat, подключенные через API iLink Bot, могут отображать Markdown напрямую, поэтому адаптер сохраняет Markdown, а не переписывает его:

Разбиение сообщений на части

Сообщения доставляются как одно сообщение чата, если они соответствуют ограничениям платформы. Для доставки разделяются только негабаритные грузы:

Индикаторы набора текста

Адаптер показывает статус набора текста в клиенте WeChat:

  1. При поступлении сообщения адаптер получает typing_ticket через API getconfig.
  2. Билеты на набор текста кэшируются по 10 минут на каждого пользователя.
  3. send_typing отправляет сигнал начала набора текста; stop_typing отправляет сигнал прекращения набора текста.
  4. Шлюз автоматически активирует индикаторы набора текста, пока агент обрабатывает сообщение.

Соединение с длинным опросом

Адаптер использует длинный опрос HTTP (не WebSocket) для получения сообщений:

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

  1. Подключение: проверяет учетные данные и запускает цикл опроса.
  2. Опрос: Вызывает getupdates с таймаутом 35 секунд; сервер удерживает запрос до тех пор, пока не поступят сообщения или не истечет тайм-аут
  3. Отправка: Входящие сообщения отправляются одновременно через asyncio.create_task.
  4. Буфер синхронизации: Постоянный курсор синхронизации (get_updates_buf) сохраняется на диске, поэтому после перезапуска адаптер возобновляет работу с правильного положения.

Повторная попытка

При ошибках API адаптер использует простую стратегию повтора:

Состояние Поведение
Переходная ошибка (1–2) Повторить попытку через 2 секунды
Повторные ошибки (3+) Выключитесь на 30 секунд, затем сбросьте счетчик
Сессия истекла (errcode=-14) Пауза на 10 минут (может потребоваться повторный вход)
Тайм-аут Немедленно повторите опрос (обычное поведение при длительном опросе)

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

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

Блокировка токена

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

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

Переменная Требуется По умолчанию Описание
WEIXIN_ACCOUNT_ID ✅ — Идентификатор учетной записи бота iLink (из входа в систему QR)
WEIXIN_TOKEN ✅ — Токен iLink Bot (автоматически сохраняется при входе в QR)
WEIXIN_BASE_URL — https://ilinkai.weixin.qq.com iLink API base URL
WEIXIN_CDN_BASE_URL — https://novac2c.cdn.weixin.qq.com/c2c Базовый URL-адрес CDN для передачи мультимедиа
WEIXIN_DM_POLICY — open Политика доступа к DM: open, allowlist, disabled, pairing
WEIXIN_GROUP_POLICY — disabled Политика группового доступа: open, allowlist, disabled
WEIXIN_ALLOWED_USERS — (пусто) Идентификаторы пользователей, разделенные запятыми, для белого списка DM
WEIXIN_GROUP_ALLOWED_USERS — (пусто) Разделенные запятыми идентификаторы групповых чатов (не идентификаторы пользователей-участников) для белого списка группы. Имя переменной является устаревшим — оно ожидает идентификаторы групп, а не идентификаторы пользователей.
WEIXIN_HOME_CHANNEL — — Идентификатор чата для вывода cron/уведомлений
WEIXIN_HOME_CHANNEL_NAME — Home Отображаемое имя домашнего канала
WEIXIN_ALLOW_ALL_USERS — — Флаг уровня шлюза, разрешающий всем пользователям (используется мастером установки)

Поиск неисправностей

Проблема Исправить
Weixin startup failed: aiohttp and cryptography are required Установите оба: pip install aiohttp cryptography
Weixin startup failed: WEIXIN_TOKEN is required Запустите hermes gateway setup, чтобы завершить вход по QR, или установите WEIXIN_TOKEN вручную
Weixin startup failed: WEIXIN_ACCOUNT_ID is required Установите WEIXIN_ACCOUNT_ID в своем .env или запустите hermes gateway setup
Another local Hermes gateway is already using this Weixin token Сначала остановите другой экземпляр шлюза — разрешен только один опросчик на каждый токен
Сессия истекла (errcode=-14) Срок действия вашего сеанса входа в систему истек. Повторно запустите hermes gateway setup, чтобы отсканировать новый QR-код
Срок действия QR-кода истек во время установки QR автоматически обновляется до 3 раз. Если срок его действия продолжает истекать, проверьте сетевое соединение
Бот не отвечает в личные сообщения Проверьте WEIXIN_DM_POLICY — если установлено значение allowlist, отправитель должен находиться в WEIXIN_ALLOWED_USERS
Бот игнорирует групповые сообщения По умолчанию групповая политика имеет значение disabled. Установите WEIXIN_GROUP_POLICY=open или allowlist — но учтите, что идентификаторы ботов iLink с QR-входом (...@im.bot) обычно вообще не могут получать обычные групповые сообщения WeChat. Если в журналах шлюза не отображаются необработанные входящие события для групповых сообщений, ограничение существует на стороне iLink, а не в Hermes.
Загрузка/загрузка мультимедиа не удалась Убедитесь, что cryptography установлен. Проверьте доступ к сети novac2c.cdn.weixin.qq.com
Blocked unsafe URL (SSRF protection) URL-адрес исходящего мультимедиа указывает на частный/внутренний адрес. Разрешены только общедоступные URL-адреса
Голосовые сообщения отображаются в виде текста Если WeChat предоставляет транскрипцию, адаптер использует текст. Это ожидаемое поведение
Сообщения дублируются Адаптер выполняет дедупликацию по идентификатору сообщения. Если вы видите дубликаты, проверьте, запущено ли несколько экземпляров шлюза
iLink POST ... HTTP 4xx/5xx Ошибка API сервиса iLink. Проверьте действительность вашего токена и подключение к сети
QR-код терминала не отображается Переустановите с дополнительными сообщениями: pip install hermes-agent[messaging]. Либо откройте URL-адрес, напечатанный над QR