Skip to content

feat(gateway): add native Weixin/WeChat support via iLink Bot API#7166

Merged
teknium1 merged 3 commits into
mainfrom
hermes/hermes-62b22a1e
Apr 10, 2026
Merged

feat(gateway): add native Weixin/WeChat support via iLink Bot API#7166
teknium1 merged 3 commits into
mainfrom
hermes/hermes-62b22a1e

Conversation

@teknium1

Copy link
Copy Markdown
Contributor

Summary

Adds a first-class Weixin (personal WeChat) platform adapter via Tencent's iLink Bot API. Salvaged from PR #6747 by @bravohenry (Zihan Huang) — contributor commits preserved with original authorship.

What's included

New adapter (gateway/platforms/weixin.py — 1669 lines)

  • Long-poll inbound delivery via iLink getupdates
  • AES-128-ECB encrypted CDN media upload/download
  • QR-code login flow for the gateway setup wizard
  • context_token persistence for reply continuity
  • DM/group access policies with allowlists
  • Native text, image, video, file, voice handling
  • Markdown formatting: heading → 【Title】, tables → bullet lists, code fences preserved
  • Block-aware message chunking (4000 char limit, doesn't split code blocks)
  • Typing indicators via getconfig/sendtyping
  • SSRF protection on remote media downloads
  • Message deduplication with TTL

Full gateway integration (15 files)

  • Platform.WEIXIN enum + _apply_env_overrides()
  • Adapter creation, authorization maps, update command
  • Cron delivery routing + send_message tool with native media
  • hermes-weixin toolset + hermes-gateway includes
  • Channel directory, prompt builder hint
  • CLI: status display, hermes tools mapping, gateway setup wizard
  • Docs: weixin.md page + environment variables reference + sidebar

Salvage fixes (not in original PR)

  • Removed sys.path.insert hack — leftover from standalone development
  • Added token lock (acquire_scoped_lock/release_scoped_lock) — prevents duplicate pollers across profiles
  • Fixed get_connected_platforms — WEIXIN requires both token AND account_id; the check must precede the generic token/api_key check
  • Added WEIXIN_HOME_CHANNEL_NAME to _EXTRA_ENV_KEYS
  • Created docs page (weixin.md) and updated environment variables reference

API limitations (confirmed via research)

The iLink Bot API supports only 5 item types: text, image, voice, file, video. No buttons, inline keyboards, card messages, or quick replies. Interactive features (approve/deny, /model selection) work via standard text-based slash commands.

Tests

  • 14 Weixin-specific tests pass (formatting, config, target parsing, send routing, SSRF protection)
  • 68 related tests pass (test_config + test_send_message_tool + test_weixin)
  • 2387 gateway suite tests pass; 26 pre-existing failures unrelated to Weixin

Credits

Original PR #6747 by @bravohenry (Zihan Huang) — 3 commits cherry-picked with authorship preserved.

bravohenry and others added 2 commits April 10, 2026 05:20
Add first-class Weixin platform adapter for personal WeChat accounts:
- Long-poll inbound delivery via iLink getupdates
- AES-128-ECB encrypted CDN media upload/download
- QR-code login flow for gateway setup wizard
- context_token persistence for reply continuity
- DM/group access policies with allowlists
- Native text, image, video, file, voice handling
- Markdown formatting with header rewriting and table-to-list conversion
- Block-aware message chunking (preserves fenced code blocks)
- Typing indicators via getconfig/sendtyping
- SSRF protection on remote media downloads
- Message deduplication with TTL

Integration across all gateway touchpoints:
- Platform enum, config, env overrides, connected platforms check
- Adapter creation in gateway runner
- Authorization maps (allowed users, allow all)
- Cron delivery routing
- send_message tool with native media support
- Toolset definition (hermes-weixin)
- Channel directory (session-based)
- Platform hint in prompt builder
- CLI status display
- hermes tools default toolset mapping

Co-authored-by: Zihan Huang <bravohenry@users.noreply.github.com>
- Remove sys.path.insert hack (leftover from standalone dev)
- Add token lock (acquire_scoped_lock/release_scoped_lock) in
  connect()/disconnect() to prevent duplicate pollers across profiles
- Fix get_connected_platforms: WEIXIN check must precede generic
  token/api_key check (requires both token AND account_id)
- Add WEIXIN_HOME_CHANNEL_NAME to _EXTRA_ENV_KEYS
- Add gateway setup wizard with QR login flow
- Add platform status check for partially configured state
- Add weixin.md docs page with full adapter documentation
- Update environment-variables.md reference with all 11 env vars
- Update sidebars.ts to include weixin docs page
- Wire all gateway integration points onto current main

Salvaged from PR #6747 by Zihan Huang.
@github-actions

Copy link
Copy Markdown
Contributor

⚠️ Supply Chain Risk Detected

This PR contains patterns commonly associated with supply chain attacks. This does not mean the PR is malicious — but these patterns require careful human review before merging.

⚠️ WARNING: base64 encoding/decoding detected

Base64 has legitimate uses (images, JWT, etc.) but is also commonly used to obfuscate malicious payloads. Verify the usage is appropriate.

Matches (first 20):

825:+    return base64.b64encode(str(value).encode("utf-8")).decode("ascii")
973:+    decoded = base64.b64decode(aes_key_b64)
1912:+                and base64.b64encode(bytes.fromhex(str((item.get("image_item") or {}).get("aeskey")))).decode("ascii")
2175:+            aes_key_b64=base64.b64encode(aes_key).decode("ascii"),

Automated scan triggered by supply-chain-audit. If this is a false positive, a maintainer can approve after manual review.

…oints

Systematic audit found Weixin missing from:

Code:
- gateway/run.py: early WEIXIN_ALLOW_ALL_USERS env check
- gateway/platforms/webhook.py: cross-platform delivery routing
- hermes_cli/dump.py: platform detection for config export
- hermes_cli/setup.py: hermes setup wizard platform list + _setup_weixin
- hermes_cli/skills_config.py: platform labels for skills config UI

Docs (11 pages):
- developer-guide/architecture.md: platform adapter listing
- developer-guide/cron-internals.md: delivery target table
- developer-guide/gateway-internals.md: file tree
- guides/cron-troubleshooting.md: supported platforms list
- integrations/index.md: platform links
- reference/toolsets-reference.md: toolset table
- user-guide/configuration.md: platform keys for tool_progress
- user-guide/features/cron.md: delivery target table
- user-guide/messaging/index.md: intro text, feature table,
  mermaid diagram, toolset table, setup links
- user-guide/messaging/webhooks.md: deliver field + routing table
- user-guide/sessions.md: platform identifiers table
@github-actions

Copy link
Copy Markdown
Contributor

⚠️ Supply Chain Risk Detected

This PR contains patterns commonly associated with supply chain attacks. This does not mean the PR is malicious — but these patterns require careful human review before merging.

⚠️ WARNING: base64 encoding/decoding detected

Base64 has legitimate uses (images, JWT, etc.) but is also commonly used to obfuscate malicious payloads. Verify the usage is appropriate.

Matches (first 20):

837:+    return base64.b64encode(str(value).encode("utf-8")).decode("ascii")
985:+    decoded = base64.b64decode(aes_key_b64)
1924:+                and base64.b64encode(bytes.fromhex(str((item.get("image_item") or {}).get("aeskey")))).decode("ascii")
2187:+            aes_key_b64=base64.b64encode(aes_key).decode("ascii"),

⚠️ WARNING: Install hook files modified

These files can execute code during package installation or interpreter startup.

Files:

hermes_cli/setup.py

Automated scan triggered by supply-chain-audit. If this is a false positive, a maintainer can approve after manual review.

@teknium1 teknium1 merged commit 7cec784 into main Apr 10, 2026
5 of 7 checks passed
@linxule

linxule commented Apr 10, 2026

Copy link
Copy Markdown
Contributor

Nice to see WeChat land! I had an earlier adapter PR open at #2502 (March 22, iLink 2.1.7 protocol) that went through a few review rounds — happy to see the feature ship either way.

I can help test this on a Raspberry Pi 4B (aarch64, Raspberry Pi OS) with a real WeChat account if that's useful. Already have a gateway running on it with Telegram + frp tunneling, so spinning up a Weixin adapter alongside would be straightforward.

Anything specific you'd want validated beyond the basic send/receive flow?

@1000cm

1000cm commented Apr 11, 2026

Copy link
Copy Markdown

I would like to report a significant change in the output format on WeChat following the recent upgrade. The formatting has shifted from a cohesive, structured table to fragmented, individual message bubbles, which significantly impacts readability.

@bravohenry

Copy link
Copy Markdown
Contributor

I would like to report a significant change in the output format on WeChat following the recent upgrade. The formatting has shifted from a cohesive, structured table to fragmented, individual message bubbles, which significantly impacts readability.

I'm going to fix it :)

@jaypark0006

Copy link
Copy Markdown
image

Very cool!!!
I think it’s very stable.
But how can I introduce Hermes to a second user? Right now, the bot can’t be added or accessed by other users.

@lijiajun1997

Copy link
Copy Markdown

it does not support wechat group yet?it's confusing in settings

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

6 participants