feat(gateway): Add WeChat platform adapter with long-poll architecture

[Alex4Xu]

Summary

Add a complete WeChat (personal) messaging platform adapter following the official Tencent openclaw-weixin plugin architecture.

What this adds

• WeChatAdapter (gateway/platforms/wechat.py) - Full adapter lifecycle: QR login, continuous polling, inbound/outbound message handling for text, images, files, voice, and video
• WeChatTransport (gateway/platforms/wechat_transport.py) - Raw HTTP wrappers, header building, base_info injection, long-poll API, CDN upload pipeline, media send/receive with AES decryption
• WeChatStateStore (gateway/platforms/wechat_state.py) - Account store, sync cursor persistence, context-token caching
• 73 tests (tests/gateway/test_wechat.py) - Covering login state transitions, polling, message conversion, media routing, session-expired pause behavior, typing tickets, and payload shapes

Key design decisions

• Long-poll based (not webhook), matching the official Tencent plugin
• context_token continuity for session management, cached per account+user
• Media logic isolated in transport layer, not the adapter
• AES decryption for inbound image/media downloads
• errcode=-14 session expiry handled with account pause (not hammering retries)
• base_info.channel_version injected on all API requests

Files changed

File	Lines	Description
gateway/platforms/wechat.py	493	Adapter: login, poll loop, send/receive
gateway/platforms/wechat_transport.py	~600	Transport: HTTP, upload, download, headers
gateway/platforms/wechat_state.py	~100	State: accounts, cursors, tokens
tests/gateway/test_wechat.py	76KB	73 tests, all passing

Registration points (already present in upstream)

• gateway/config.py: Platform.WECHAT enum member
• hermes_cli/tools_config.py: WeChat entry in PLATFORMS dict
• hermes_cli/skills_config.py: WeChat entry in PLATFORMS dict
• toolsets.py: hermes-wechat toolset definition
• hermes_cli/main.py: hermes wechat CLI commands

Testing

uv run --extra dev python -m pytest tests/gateway/test_wechat.py -q
# 73 passed in 1.42s

Motivation

WeChat is the dominant messaging platform in China. This adapter enables Hermes users to interact with the agent via WeChat personal accounts using the official Tencent iLink bot protocol, expanding Hermes's multi-platform gateway to cover this critical market.

Notes

This PR mirrors the official Tencent openclaw-weixin plugin architecture rather than inventing a webhook/proxy design. The code has been tested with two live WeChat bot accounts.

[trevorgordon981]

Substantial. 3080 lines of new code for a complete platform adapter is one of the biggest single PRs on this repo. Architectural choices look sound: long-poll matching the official Tencent plugin (vs. reinventing with webhooks), transport/adapter/state separation, isolated media logic with AES decryption, session-expiry account pause instead of retry hammering. 73 tests is solid coverage. Two questions worth flagging for long-running infra: how does the context_token cache invalidate when an account reconnects mid-session, and does the polling loop back off if the server repeatedly returns 429/503, or retry at constant cadence? Those are the two places long-poll adapters typically erode over time. Non-blocking. Proceed.

[Alex4Xu]

Thanks for the thorough review — both questions pointed at real issues.

Ran verification tests against both before patching (using GLM-5.1 + Claude Code), and confirmed:

context_token cache on reconnect: Cache was never cleared on WeChatSessionExpiredError. A stale token would persist across reconnects and get passed on subsequent sends. Fixed in _poll_account_loop: WeChatStateStore.clear_context_tokens(account_id) is now called before pausing the account, so any reconnect starts with a clean slate.

Polling backoff on 429/503: The loop was using min(consecutive_failures, 5) for all exceptions with no distinction — confirmed max backoff of only 3s after 3 consecutive rate-limit errors. Fixed by introducing WeChatRateLimitError in the transport layer (_api_get / _api_post now raise it explicitly on 429/503), caught separately in the loop with exponential backoff min(2 ** consecutive_failures, 60) capped at 60s.

Both fixes are covered by new regression tests added to test_wechat.py. Appreciate you catching these before they caused trouble in prod.

[teknium1]

Merged via PR #8665 which synthesizes the best fixes from ~25 community PRs into a single consolidated change. Your contribution (WeChat long-poll adapter) was reviewed and informed the final implementation. Thank you @Alex4Xu for your work on this!