Hermes Agent WeChat setup: Weixin, WeCom bot and WeCom callback

Three routes, and which one fits

• Weixin, the personal account. Hermes logs in through Tencent’s iLink Bot API by QR code and receives messages by long polling, so it needs no public address. Pick this to talk to your own agent from your own WeChat, or to let a few known people do the same.
• WeCom AI Bot. Needs a WeCom organisation. Hermes holds a WebSocket connection to WeCom’s AI Bot gateway, again with no public address. Pick this for a team or company that already lives in WeCom, especially if you want the agent in group chats.
• WeCom callback. A self-built WeCom application: WeCom pushes encrypted messages to a public HTTP address that you run. It shows up as an app in people’s WeCom sidebar and can route several corporations. Pick it only if you need that, because it is the heaviest to set up and the most limited in what it can do (see below).

The two WeCom routes need an account in a WeCom organisation, and the callback route needs admin access to it. All three need a Hermes gateway that stays running; if you have not installed Hermes yet, start with how to install Hermes Agent.

Weixin (personal WeChat): QR login and setup

The guided route is hermes gateway setup. Choose Weixin / WeChat and the wizard:

1. asks whether to start QR login, then requests a QR code from the iLink service and shows it in the terminal (it also prints a link in case the terminal cannot draw it);
2. waits for you to scan it in WeChat and confirm on the phone;
3. saves the returned account ID and token (as WEIXIN_ACCOUNT_ID and WEIXIN_TOKEN in ~/.hermes/.env);
4. asks how direct messages should be authorised and whether to allow group chats, then offers to set a home chat.

An unscanned code expires and is refreshed up to three times before the wizard gives up, and the whole login times out after eight minutes. The adapter needs the Python packages aiohttp and cryptography. Terminal QR rendering requires qrcode, which is included in the messaging extra or can be installed separately. Then start the gateway:

hermes gateway

The keys the adapter reads, all optional once login is saved:

WEIXIN_DM_POLICY=pairing
WEIXIN_ALLOWED_USERS=user_id_1,user_id_2
WEIXIN_GROUP_POLICY=disabled
WEIXIN_HOME_CHANNEL=chat_id

The access settings also exist under platforms.weixin.extra in config.yaml (dm_policy, allow_from, group_policy, group_allow_from); the home chat is a separate setting, platforms.weixin.home_channel. Hermes takes a local lock on the token, so a second gateway on the same machine refuses to start with it. The lock does not stop another machine or container from using the same token, so run one gateway per account. Keep it running as a service (hermes gateway install) so it survives a closed terminal.

One thing surprises people. QR login does not turn your personal account into the bot. It connects an iLink bot identity, a separate WeChat contact. You and your allowed people chat with that contact; the account that scanned the code is not the bot.

WeCom AI Bot: Bot ID, secret and groups

Run hermes gateway setup and choose WeCom. The recommended path is scan-to-create: scan the QR code with the WeCom mobile app and Hermes obtains a Bot ID and Secret for you. If that is not available, the wizard asks for them by hand; its manual steps are to open the WeCom app, go to Workspace, then Smart Robot, create one in API mode, and copy the Bot ID and Secret. Or set the keys yourself in ~/.hermes/.env:

WECOM_BOT_ID=your-bot-id
WECOM_SECRET=your-secret
WECOM_ALLOWED_USERS=user_id_1,user_id_2
WECOM_GROUP_POLICY=allowlist
WECOM_HOME_CHANNEL=chat_id

Treat the secret like a password: anyone who has it can impersonate your bot. Then run hermes gateway. The adapter streams replies natively, so the WeCom client shows a thinking bubble and the answer fills in as it is written; set display.platforms.wecom.streaming: false to turn that off. It reconnects on its own with a growing delay if the connection drops.

For groups, set WECOM_GROUP_POLICY yourself. The documentation says it defaults to open, but in the 0.21.5 code the default is pairing, and that value does not pass group messages through at all. With allowlist, list the group IDs under platforms.wecom.extra.group_allow_from in config.yaml. You can restrict who may speak inside each group with platforms.wecom.extra.groups.<group_id>.allow_from, and a "*" entry under groups sets the default for other groups.

WeCom callback: the self-built app route

Create a self-built application in the WeCom admin console and note the Corp ID, create a Corp Secret, and note the Agent ID. Under Receive Messages, set a callback URL plus a Token and an EncodingAESKey. Then give Hermes the same values:

WECOM_CALLBACK_CORP_ID=your-corp-id
WECOM_CALLBACK_CORP_SECRET=your-corp-secret
WECOM_CALLBACK_AGENT_ID=1000002
WECOM_CALLBACK_TOKEN=your-callback-token
WECOM_CALLBACK_ENCODING_AES_KEY=your-43-char-aes-key
WECOM_CALLBACK_PORT=8645
WECOM_CALLBACK_ALLOWED_USERS=user1,user2

The gateway then listens on port 8645 at the path /wecom/callback. WeCom has to reach that address from the internet, so you need a public server, reverse proxy or tunnel in front of it. The Hermes documentation shows an http:// example URL but also notes that WeCom rejects plain HTTP, so plan on HTTPS. A listener bound to loopback is fine when a reverse proxy or tunnel on the same machine forwards to it.

The limits are real, so read them before choosing this route:

• Input is text only; images, files and voice sent to the app are not handled.
• No streaming and no typing indicator: the reply arrives whole, after the agent finishes.
• The reply is sent through WeCom’s send API, and the code cuts each text at 2,048 characters.
• The documentation warns that agent sessions can take 3 to 30 minutes, so users may wait for the answer.

Common failures are a Token that differs from the one in WeCom, an EncodingAESKey that was cut short when copied (the signature check fails), and a callback URL WeCom cannot reach.

Who can message your agent, and what about groups

The agent can run commands and edit files, so decide this before you share the contact. Both adapters use the same four direct-message policies: open, allowlist, pairing and disabled.

• Pairing is the default in the 0.21.5 code for both Weixin and the WeCom bot (the documentation says open; the code wins). An unknown person who messages the bot gets a code, and you approve it with hermes pairing approve weixin <code> (use wecom for the bot). The wizard recommends it.
• Allowlist: only IDs in WEIXIN_ALLOWED_USERS or WECOM_ALLOWED_USERS (WECOM_CALLBACK_ALLOWED_USERS for the callback app) get through. Weixin IDs are not WeChat names. To collect them, first select pairing mode in hermes gateway setup and restart the gateway. Have each person message the bot, then run hermes pairing list to read their full User ID. Run setup again, choose “Only allow listed user IDs”, enter those IDs, and restart the gateway.
• Open: for Weixin and the WeCom bot, open only works together with an explicit opt-in such as WEIXIN_ALLOW_ALL_USERS=true (or the general GATEWAY_ALLOW_ALL_USERS). The callback route uses WECOM_CALLBACK_ALLOW_ALL_USERS=true. It is a poor idea for an agent that can act on your machine.

Groups differ a lot. For personal Weixin, group policy defaults to disabled, and the Hermes documentation is blunt that an iLink bot identity generally cannot be invited into ordinary WeChat groups and does not receive their events. The group settings only matter if iLink actually delivers group events for your account type; most setups get direct messages only, and Hermes logs a warning at startup if you enable group policy. Note also that WEIXIN_GROUP_ALLOWED_USERS takes group IDs, not member IDs, despite its name. The WeCom bot is the route built for groups, with the per-group sender lists described above. The callback app is person-to-app.

Media, message limits and risks

• Weixin media: images, video, files and voice are received and can be sent; media moves through Tencent’s encrypted CDN and Hermes handles the encryption. When the voice audio is available, Hermes downloads it and transcribes it itself, using WeChat’s own transcript only when there is no audio. Voice the agent sends goes out as a file. Long replies are split into several messages (the code splits at 2,000 characters; the documentation says 4,000), and Markdown is kept as Markdown.
• WeCom bot uploads: images and video up to 10 MB, native voice up to 2 MB and only in AMR format, files up to 20 MB. An image, video or voice clip over its limit but under 20 MB is sent as a plain file instead, as is non-AMR audio; over 20 MB it is refused. An ordinary text reply is capped at 4,000 characters.
• Sessions and continuity: Weixin keeps a context token for each contact. If a send fails because that token has expired, Hermes retries once without it; if delivery still fails, ask the contact to message the bot again and check the gateway log.
• Always-on: all three routes work only while the gateway is running. A laptop that sleeps means a silent bot.
• Third-party dependence: Weixin runs on Tencent’s iLink service, and WeCom on WeCom’s gateway. Hermes cannot change what those services allow, and the documentation itself calls the group limits an iLink-side limitation. Test with a spare setup before relying on it for something important.

Common errors and fixes

• WEIXIN_TOKEN is required or WEIXIN_ACCOUNT_ID is required. Login was never completed. Run hermes gateway setup again.
• Session expired (errcode=-14). While polling for messages, Hermes pauses for ten minutes when it sees this. If the login has really expired, scan a new QR code with hermes gateway setup.
• The QR code keeps expiring. It refreshes three times. Check your network access to Tencent, or open the printed link if the terminal drawing is unreadable.
• It answers you but nobody else. Others must message the iLink bot contact, not your personal account, and must be allowed (paired or on WEIXIN_ALLOWED_USERS).
• Group messages never arrive. See the group notes above; on personal Weixin this is usually the iLink limit, not a Hermes setting.
• invalid secret (errcode=40013) on WeCom. The secret does not match the bot’s credentials. Copy it again.
• Nothing happens on the WeCom callback. Check the Token and EncodingAESKey, and that the public callback URL reaches the gateway on the right port and path.
• Media fails to download or decrypt. Check the gateway log for the specific error. If WeCom reports that cryptography is missing, install it in the Hermes Python environment and restart the gateway. Weixin checks this dependency before connecting; download, AES-key, padding and size-limit errors need their own fixes.

WeChat on ReadyHermes

ReadyHermes offers the personal Weixin route only. There is no WeCom bot or WeCom callback option in the workspace, so if you need WeCom you would run Hermes yourself. Your agent runs on our servers and stays on, so there is no gateway to keep alive. To connect:

1. In the workspace, open Channels and choose WeChat.
2. Wait for the QR code.
3. Scan it with WeChat on your phone and confirm on the phone. The bot itself runs on our servers.
4. The panel then moves on to a pairing step. Message your assistant from WeChat; if it replies with a code, paste it into the panel and approve. If the panel says the account was already paired, you are set.

When the code is scanned, the account that scanned it is added to the allowed senders, and everyone else starts on pairing, with group chats switched off. The Channels panel needs an active trial or paid plan, and connect attempts are limited to six per hour. WeChat sits alongside Telegram, WhatsApp, Discord and Lark there; see also Telegram and WhatsApp. For the choice between running it yourself and a hosted agent, see self-hosting versus managed hosting.