Connect Hermes Agent to WeChat
Chat with Hermes Agent directly inside WeChat. Scan a QR code to connect, send messages in DMs or group chats, and share the same AI context across all your connected platforms.
What You Can Do
The Hermes Agent WeChat gateway connects your local agent to WeChat — use skills, memory, and all platform features from inside your WeChat chats.
Chat from WeChat
Your Hermes agent runs on your machine. WeChat is just the interface — send messages from any device where you're logged in to WeChat.
Voice & media support
Send voice memos, images, video, or files. Hermes receives and processes them automatically, with transcription for voice messages when available.
Group chat ready
Add the bot to a WeChat group and control which groups it responds in. Group messaging is disabled by default and can be enabled with a single config line.
Shared context across platforms
Your Hermes agent remembers conversations across all connected platforms. Start a task on Telegram, continue it on WeChat — the same session, the same model, the same memory.
Before You Start
Make sure you have these ready before running the setup wizard.
- ✓Hermes is installed and running→ /install
- ✓LLM API is configured→ /models
- ✓You have a personal WeChat account (not WeCom)
- ✓Dependencies installed:
pip install aiohttp cryptography
Setup
Install dependencies
aiohttp and cryptography aiohttp and cryptography are required. Without them, the gateway will refuse to start with an explicit error.
The qrcode package is optional — if not installed, the setup wizard prints a URL you can open in a browser instead.
Scan to connect
Select Weixin when prompted. The wizard will:
- Request a QR code from the iLink Bot API
- Display the QR code in your terminal (or print a URL to open)
- Wait for you to scan it with the WeChat mobile app
- Ask you to confirm the login on your phone
- Save credentials automatically to ~/.hermes/weixin/accounts/
Once confirmed, you'll see:
Your account_id, token, and base_url are saved automatically. You don't need to copy anything manually.
Start the gateway
The adapter restores your saved credentials, connects to the iLink API, and begins long-polling for messages. You should see:
Open WeChat and find the bot conversation that appeared after scanning. Send any message — you'll get a pairing code back.
Approve your access
By default, the DM policy is set to pairing mode. When you send a message to the bot for the first time, it replies with a pairing code instead of a normal response:
On the machine running Hermes, approve the code:
The bot will confirm approval and respond normally to all future messages. You only need to do this once per WeChat account.
Verify
Send the bot these messages to confirm each layer is working:
| Message to send | Expected result |
|---|---|
Hello | Agent replies in text |
| A voice memo | Agent transcribes and replies |
/model | Shows current model |
/skill arxiv | Loads the arxiv skill |
If Hello gets no reply, make sure you completed the pairing step above.
WeChat vs. Telegram: One Key Difference
The setup experience is different from Telegram in one important way.
Unlike Telegram — where you create a dedicated bot account via BotFather, each with its own username and chat interface — WeChat uses your personal account as the bot endpoint. There is a single entry point per linked WeChat account.
This means anyone who wants to chat with your Hermes agent needs to message you directly on WeChat, or be part of a group where the gateway is active. There is no separate "@botname" to share — you share your WeChat ID instead.
For multi-user setups, the gateway lets you configure which WeChat contacts or groups the agent responds to. The DM policy (open / pairing / allowlist) controls who can chat without manual approval.
FAQ
The QR code keeps expiring before I can scan it
The QR code auto-refreshes up to 3 times. The most common causes of repeated expiry:
- Slow or unstable network — the iLink API is timing out between refreshes
- WeChat scanner was slow to open — have it ready before running setup
If all 3 retries expire, exit and run hermes gateway setup again.
Bot receives messages but never replies
Cause A — Pairing not approved
If your DM policy is pairing (the default), the bot waits for approval before responding. Check for a pending pairing code:
If a code is listed, approve it and the bot will start responding.
Cause B — Model not configured or API key expired
WeChat delivers the message to Hermes, but Hermes can't generate a reply because the LLM isn't available. The failure is completely silent — no error appears in WeChat. Check your provider dashboard for expired credits.
Cause C — Gateway is not running
The gateway must be running continuously to receive messages. If you closed the terminal, restart it with hermes gateway.
Bot ignores messages in group chats
Group messaging is disabled by default. Enable it by adding this to ~/.hermes/config.yaml:
Restart the gateway after saving the config.
Voice messages aren't being transcribed
Hermes needs a speech-to-text provider configured. The default local option uses faster-whisper:
Or set a cloud provider in ~/.hermes/.env:
What is the Hermes Agent WeChat gateway?
The Hermes Agent gateway is a process that connects your locally running Hermes Agent to messaging platforms — WeChat, Telegram, Discord, Slack, and Signal. For WeChat, it uses the iLink Bot API to authenticate via QR code and long-poll for incoming messages.
Start it with hermes gateway after completing setup. The gateway must stay running to receive messages — it's not a background service by default, but can be configured to run on boot.
My WeChat session disconnects after a while
WeChat sessions via the iLink API occasionally need re-authentication. When this happens, run hermes gateway setup again and re-scan the QR code to refresh your credentials.
To minimize disconnects, keep the gateway running on a stable connection. Avoid VPNs that rotate IPs frequently, as this can trigger WeChat's security checks.
Advanced
Optional configuration for power users.
Group mention control
When group reply is enabled, Hermes responds to every message it sees by default. To restrict it to messages that @mention your account or use a trigger prefix:
DM access policy
Controls who can send DMs to your Hermes agent. Set WEIXIN_DM_POLICY in ~/.hermes/.env:
Multiple accounts
The Weixin adapter supports multiple linked WeChat accounts. Each account gets its own credential file under ~/.hermes/weixin/accounts/. Run hermes gateway setup again to add a second account.
All accounts share the same agent and model. Responses are routed back to the account that received the original message.
Cross-platform context
Hermes maintains a unified conversation history across all connected platforms by default. If you're also running the Telegram gateway, your WeChat and Telegram conversations share the same session and memory.
To isolate platforms into separate sessions, set session_scope: platform in your config.
This guide covers Hermes Agent WeChat setup. The same gateway also supports Telegram, Discord, Slack, and Signal. For the full configuration reference and enterprise WeCom support, see the official documentation.