🏠 Главная › user guide › weixin

Вейсинь (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. Шлюз регистрирует «ПРЕДУПРЕЖДЕНИЕ» при запуске каждый раз, когда для «WEIXIN_GROUP_POLICY» установлено любое значение, кроме «отключено».

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

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

pip install aiohttp cryptography
# Optional: for terminal QR code display
cd ~/.hermes/hermes-agent && uv pip install -e ".[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 (обязательно)
жетон — Токен iLink Bot (обязательно, автоматически сохраняется при входе в QR)
base_url https://ilinkai.weixin.qq.com Базовый URL-адрес API iLink
cdn_base_url https://novac2c.cdn.weixin.qq.com/c2c Базовый URL-адрес CDN для передачи мультимедиа
dm_policy открытый Доступ к DM: «открытый», «белый список», «отключен», «сопряжение»
group_policy инвалид Групповой доступ: «открытый», «белый список», «отключенный»
allow_from [] Идентификаторы пользователей, разрешенные для личных сообщений (когда dm_policy=allowlist)
group_allow_from [] Идентификаторы групп разрешены (когда group_policy=allowlist)
split_multiline_messages ложь Если установлено значение true, многострочные ответы разбиваются на несколько сообщений чата (устаревшее поведение). Если установлено значение false, многострочные ответы сохраняются как одно сообщение, если они не превышают ограничение по длине.
text_batch_delay_секунды 3.0 Период молчания (в секундах), прежде чем буферизованный пакет быстрых текстовых сообщений будет сброшен как один объединенный запрос. iLink доставляет сообщения индивидуально, поэтому этот метод устранения дребезга позволяет избежать одного вызова агента для каждого фрагмента. Установите 0, чтобы отправлять каждое сообщение немедленно.
text_batch_split_delay_секунды 5.0 Расширенная задержка сброса используется, когда последний фрагмент приближается к порогу разделения (длинные сообщения iLink могли быть разбиты на фрагменты).

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

Политика DM

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

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

WEIXIN_ALLOWED_USERS — это входящий фильтр, не являющийся системой приглашений. QR-код Вход в систему позволяет подключить один идентификатор бота iLink к Hermes. Другие люди не сканируют QR-код Hermes со своими учетными записями; они должны отправить сообщение подключенному iLink бот/контакт через WeChat, а Hermes обработает DM только в том случае, если отправитель Идентификатор пользователя Weixin находится в WEIXIN_ALLOWED_USERS.

Практический порядок настройки:

  1. Один раз выполните подключение Hermes с помощью «настройки шлюза Hermes» и обратите внимание на подключенного бота iLink. счет.
  2. Попросите каждого разрешенного пользователя отправить прямое сообщение этому боту/контакту.
  3. Прочтите идентификатор отправителя/пользователя из шлюза журналов или источников данных о входящих событиях.
  4. Добавьте эти идентификаторы в WEIXIN_ALLOWED_USERS, а затем перезапустите шлюз.

Если только учетная запись, отсканировавшая QR-код, может связаться с Hermes, убедитесь, что Другие пользователи отправляют сообщения самому боту iLink, а не личному WeChat. учетная запись, которая выполнила вход по QR. Бот iLink — это индивидуальная личность, и Обычная маршрутизация контактов/групп WeChat может быть ограничена действиями Tencent iLink.

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

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

Значение Поведение
открытый Бот отвечает во всех группах (в случае проведения мероприятия)
белый список Бот отвечает только на группы с идентификаторами, запросы в group_allow_from (если события допускаются)
инвалид Все групповые сообщения игнорируются (по умолчанию)
```bash
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
```

📝 Note
The default group policy is disabled for Weixin (unlike WeCom where it defaults to open). This is intentional — personal WeChat accounts may be in many groups, and iLink bot identities typically can't receive ordinary WeChat group messages at all. The gateway logs a WARNING at startup if you set WEIXIN_GROUP_POLICY to anything other than disabled.
## Media Support

Inbound (receiving)

The adapter receives media attachments from users, downloads them from the WeChat CDN, decrypts them, and caches them locally for agent processing:

Type How it's handled
Images Downloaded, AES-decrypted, and cached as JPEG.
Video Downloaded, AES-decrypted, and cached as MP4.
Files Downloaded, AES-decrypted, and cached. Original filename is preserved.
Voice If a text transcription is available, it's extracted as text. Otherwise the audio (SILK format) is downloaded and cached.

Quoted messages: Media from quoted (replied-to) messages is also extracted, so the agent has context about what the user is replying to.

AES-128-ECB Encrypted CDN

WeChat media files are transferred through an encrypted CDN. The adapter handles this transparently:

No configuration is needed — encryption and decryption happen automatically.

Outbound (sending)

Method What it sends
send Text messages with Markdown formatting
send_image / send_image_file Native image messages (via CDN upload)
send_document File attachments (via CDN upload)
send_video Video messages (via CDN upload)

All outbound media goes through the encrypted CDN upload flow:

  1. Generate a random AES-128 key
  2. Encrypt the file with AES-128-ECB + PKCS#7 padding
  3. Request an upload URL from the iLink API (getuploadurl)
  4. Upload the ciphertext to the CDN
  5. Send the message with the encrypted media reference

Context Token Persistence

The iLink Bot API requires a context_token to be echoed back with each outbound message for a given peer. The adapter maintains a disk-backed context token store:

This ensures reply continuity even after gateway restarts.

Markdown Formatting

WeChat clients connected through the iLink Bot API can render Markdown directly, so the adapter preserves Markdown instead of rewriting it:

Message Chunking

Messages are delivered as a single chat message whenever they fit within the platform limit. Only oversized payloads are split for delivery:

Typing Indicators

The adapter shows typing status in the WeChat client:

  1. When a message arrives, the adapter fetches a typing_ticket via the getconfig API
  2. Typing tickets are cached for 10 minutes per user
  3. send_typing sends a typing-start signal; stop_typing sends a typing-stop signal
  4. The gateway automatically triggers typing indicators while the agent processes a message

Long-Poll Connection

The adapter uses HTTP long-polling (not WebSocket) to receive messages:

How It Works

  1. Connect: Validates credentials and starts the poll loop
  2. Poll: Calls getupdates with a 35-second timeout; the server holds the request until messages arrive or the timeout expires
  3. Dispatch: Inbound messages are dispatched concurrently via asyncio.create_task
  4. Sync buffer: A persistent sync cursor (get_updates_buf) is saved to disk so the adapter resumes from the correct position after restarts

Retry Behavior

On API errors, the adapter uses a simple retry strategy:

Condition Behavior
Transient error (1st–2nd) Retry after 2 seconds
Repeated errors (3+) Back off for 30 seconds, then reset counter
Session expired (errcode=-14) Pause for 10 minutes (re-login may be needed)
Timeout Immediately re-poll (normal long-poll behavior)

Deduplication

Inbound messages are deduplicated using message IDs with a 5-minute window. This prevents double-processing during network hiccups or overlapping poll responses.

Token Lock

Only one Weixin gateway instance can use a given token at a time. The adapter acquires a scoped lock on startup and releases it on shutdown. If another gateway is already using the same token, startup fails with an informative error message.

All Environment Variables

Variable Required Default Description
WEIXIN_ACCOUNT_ID ✅ — iLink Bot account ID (from QR login)
WEIXIN_TOKEN ✅ — iLink Bot token (auto-saved from QR login)
WEIXIN_BASE_URL — https://ilinkai.weixin.qq.com iLink API base URL
WEIXIN_CDN_BASE_URL — https://novac2c.cdn.weixin.qq.com/c2c CDN base URL for media transfer
WEIXIN_DM_POLICY — open DM access policy: open, allowlist, disabled, pairing
WEIXIN_GROUP_POLICY — disabled Group access policy: open, allowlist, disabled
WEIXIN_ALLOWED_USERS — (empty) Comma-separated user IDs for DM allowlist
WEIXIN_GROUP_ALLOWED_USERS — (empty) Comma-separated group chat IDs (not member user IDs) for group allowlist. The variable name is legacy — it expects group IDs, not user IDs.
WEIXIN_HOME_CHANNEL — — Chat ID for cron/notification output
WEIXIN_HOME_CHANNEL_NAME — Home Display name for the home channel
WEIXIN_ALLOW_ALL_USERS — — Gateway-level flag to allow all users (used by setup wizard)

Troubleshooting

Problem Fix
Weixin startup failed: aiohttp and cryptography are required Install both: pip install aiohttp cryptography
Weixin startup failed: WEIXIN_TOKEN is required Run hermes gateway setup to complete QR login, or set WEIXIN_TOKEN manually
Weixin startup failed: WEIXIN_ACCOUNT_ID is required Set WEIXIN_ACCOUNT_ID in your .env or run hermes gateway setup
Another local Hermes gateway is already using this Weixin token Stop the other gateway instance first — only one poller per token is allowed
Session expired (errcode=-14) Your login session has expired. Re-run hermes gateway setup to scan a new QR code
QR code expired during setup The QR auto-refreshes up to 3 times. If it keeps expiring, check your network connection
Bot doesn't respond to DMs Check WEIXIN_DM_POLICY — if set to allowlist, the sender must be in WEIXIN_ALLOWED_USERS
Bot ignores group messages Group policy defaults to disabled. Set WEIXIN_GROUP_POLICY=open or allowlist — but note that QR-login iLink bot identities (...@im.bot) typically cannot receive ordinary WeChat group messages at all. If the gateway logs show no raw inbound events for group messages, the limitation is on the iLink side, not in Hermes.
Media download/upload fails Ensure cryptography is installed. Check network access to novac2c.cdn.weixin.qq.com
Blocked unsafe URL (SSRF protection) The outbound media URL points to a private/internal address. Only public URLs are allowed
Voice messages show as text If WeChat provides a transcription, the adapter uses the text. This is expected behavior
Messages appear duplicated The adapter deduplicates by message ID. If you see duplicates, check if multiple gateway instances are running
iLink POST... HTTP 4xx/5xx API error from the iLink service. Check your token validity and network connectivity
Terminal QR code doesn't render Reinstall with the messaging extra: cd ~/.hermes/hermes-agent && uv pip install -e ".[messaging]". Alternatively, open the URL printed above the QR