Environment

• OS: Windows Server 2022 Datacenter 10.0.20348
• Hermes home: C:\Users\Administrator\AppData\Local\hermes
• Gateway mode: Windows background process using PowerShell Start-Process -FilePath "hermes" -ArgumentList "gateway run"
• Weixin adapter: iLink bot API / QR login
• Hermes version: TODO: paste output of hermes version
• Python version: TODO: paste output of python --version or Hermes runtime Python version

Summary

The Weixin / iLink gateway setup currently exposes group-chat configuration options, including WEIXIN_GROUP_POLICY and WEIXIN_GROUP_ALLOWED_USERS. The setup prompt says:

How should group chats be handled?
- Disable group chats (recommended)
- Allow all group chats
- Only allow listed group chat IDs

However, in our Windows environment, QR login creates/connects an iLink bot identity such as:

[email protected]

This bot identity can receive messages through its iLink bot DM entry, but it cannot be invited into an ordinary WeChat group like a normal WeChat contact. Messages sent in ordinary WeChat groups, including @ mentions of the personal WeChat account used for QR login, do not reach Hermes.

This made the setup/configuration misleading. We spent significant time debugging WEIXIN_GROUP_POLICY, WEIXIN_GROUP_ALLOWED_USERS, and WEIXIN_GROUP_MENTION_ONLY, but the problem was not Hermes filtering. The iLink API simply did not deliver ordinary group messages to the gateway.

Evidence from debugging

We temporarily added a raw inbound log at the very beginning of WeixinAdapter._process_message(), before sender checks, deduplication, group policy checks, allowlist checks, and text/media parsing.

For a successful iLink bot DM, logs showed a raw inbound event like:

[Weixin] raw inbound before filters: {
  "from_user_id": "[email protected]",
  "to_user_id": "[email protected]",
  "group_id": "",
  "message_type": 1,
  "item_list": [{"text_item": {"text": "..."}}],
  "context_token": "***"
}
[Weixin] inbound ... type=dm
inbound message: platform=weixin ...

For ordinary WeChat group messages and @ mentions, no raw inbound log appeared at all.

We then added a lower-level poll log immediately after _get_updates(...). During repeated group-message tests, iLink returned successful responses but no messages:

[Weixin] getUpdates response ret=0 errcode=0 msgs=0 sync_buf_changed=True

This confirms that the messages were not filtered by Hermes. They were not delivered by iLink to the gateway.

Why this is confusing

1. The adapter is described in setup as Weixin / WeChat personal accounts.
2. QR login uses a personal WeChat account, which makes users expect ordinary personal WeChat conversations or groups to work.
3. The generated config includes group-chat policy variables.
4. WEIXIN_GROUP_ALLOWED_USERS sounds like a user allowlist, but setup text says it is actually a list of group chat IDs.
5. In practice, the connected identity is an iLink bot ([email protected]), not a normal personal WeChat account that can be pulled into ordinary WeChat groups.

Requested changes

Please clarify the Weixin/iLink adapter documentation and setup prompts:

1. Explicitly state whether ordinary WeChat group chats are supported for QR-login iLink bots.
2. If ordinary groups are not supported, say that Weixin/iLink currently supports iLink bot DM only in this mode.
3. Make clear that @ mentioning the personal WeChat account used for QR login is not the same as @ mentioning the Hermes/iLink bot.
4. Consider hiding or disabling the group-chat setup prompt for Weixin unless the current iLink credentials/account type actually support group events.
5. Rename or document WEIXIN_GROUP_ALLOWED_USERS as group chat IDs, not group member user IDs.
6. Consider adding a startup warning when WEIXIN_GROUP_POLICY is not disabled, explaining that group delivery depends on iLink providing group events and ordinary WeChat groups may not work.

Suggested wording

Weixin/iLink QR login connects Hermes to an iLink bot identity, not to a fully automated ordinary personal WeChat account. In this mode, Hermes can receive messages sent to the iLink bot DM entry. Ordinary WeChat group messages and @ mentions of the QR-login personal account may not be delivered to Hermes unless iLink returns group events for your account/bot type.

Impact

The current UI/config caused a long and confusing debugging session. The gateway was running correctly, Weixin was connected, and DM messages to the bot worked, but ordinary group messages never reached Hermes. Clear documentation would prevent users from spending time debugging allowlists or gateway restarts for a capability that may not be supported by the iLink bot identity.