UPGPTs

English

中文

English

中文

Appearance

Hermes Agent + WeChat Guide (2026): QR-Code Binding for Personal WeChat with No Public IP, Plus Group Chat Assistant Setup ​

Author: UPGPTs TeamFirst published: 2026-08-09Last updated: 2026-09-28

TL;DR: Hermes Agent now supports personal WeChat natively — no public IP, no server, just a phone QR scan. The core flow: hermes gateway setup → choose Weixin and scan → set private-chat and group-chat authorization policies → hermes gateway restart to apply → send Hermes a message in WeChat to get an authorization code, or use /whitelist to finish binding. The whole thing takes about 5 minutes. Note: this uses a third-party interface, so trial it on a secondary account first.

If you want to use Hermes directly inside WeChat — looking things up, writing summaries, organizing group chats, running daily pushes — this guide walks the whole flow. Of the four steps, three are copy-paste commands; only the scan needs your phone.

📚 Table of Contents (click to jump) ​

1. Prerequisites: Environment Dependencies and WeChat Risk-Control Warnings ​

CheckRequirementHow to confirm
Hermes AgentInstalled and running normallyhermes update runs in the terminal; if it isn't installed, start with the Hermes install and usage guide
PythonVersion 3.10 or higherRun python --version in the terminal
WeChat accountA personal WeChat account that signs in normally — not WeCom—

⚠️ Read this risk warning before you start: connecting Hermes to WeChat uses a third-party interface (the iLink Bot API), which is not an official WeChat open capability. Automating a personal WeChat account may trigger the platform's risk controls, so strongly prefer testing on a secondary account you don't use much and only decide whether to switch after it runs stably. Also, make sure your allowlist permissions are configured properly so strangers can't trigger it unpredictably.

2. Install the Python Gateway Dependencies and Update Hermes Agent ​

You need three Python packages and one version update. Each has a purpose — don't skip any:

bash
# Needed for gateway communication and encryption
pip install aiohttp cryptography

# Draws the QR code directly in the terminal, so you don't have to hunt for a link in the logs
pip install qrcode

# WeChat support is a newer capability that older versions don't have, so updating is required
hermes update

These commands work the same on Windows PowerShell, macOS, and Linux.

💡 Dependency check tip: run pip show aiohttp cryptography qrcode — if all three correctly echo their version information, the install succeeded. If a later error reports a missing module, pip usually installed it into the system's global environment rather than the virtual environment Hermes runs in; switch to the right environment and reinstall.

3. Configure the WeChat Gateway and Bind by QR Code (hermes gateway setup) ​

Hermes provides an interactive terminal configuration, so there's no config file to hand-write:

bash
hermes gateway setup

Follow the prompts through three steps:

  1. Use the arrow keys to select Weixin / WeChat and press Enter
  2. Type Y to confirm
  3. Hermes calls the iLink Bot API and generates a WeChat binding QR code in the terminal

Then scan it with WeChat on your phone. This step responds in seconds — once you've scanned, Hermes is added to your WeChat.

Selecting Weixin in hermes gateway setup and generating the binding QR code

What the scan actually does ​

The scan establishes a channel between your WeChat and the Hermes gateway — effectively adding Hermes as a WeChat contact.

But you can't use it yet: "who can use it, and in which contexts" hasn't been decided (step 4), and the configuration hasn't taken effect (step 5).

💡 Scanning tips: QR codes expire, so the terminal reporting expiry is normal — just run hermes gateway setup again to generate a new one. When your phone shows a login confirmation prompt, tap allow to complete the connection.

4. Security: Private-Chat Authorization and WeChat Group Response Policy ​

Once the connection is made, Hermes asks you to set authorization policies — that is, who may invoke it and where.

Private-chat authorization ​

OptionMeaningWhen to choose it
DM Pairing Approval (recommended)A stranger's first direct message needs your manual approval; approved contacts pass through afterwardThe vast majority of individual users
OpenAnyone's direct message passes automaticallyWhen you genuinely want it open to everyone, such as a public service
DisableDirect messages fully offWhen you only want it in groups, or don't want DM interruptions for now

Choose DM Pairing Approval. Already-approved contacts aren't affected and keep working as before; it only blocks strangers from invoking it directly.

Group-chat authorization ​

Group chat is Disable by default, and it's best left that way, because the boundary is entirely different once group chat is on:

  • Every member of the group can issue Hermes commands, not just you
  • It reads the messages in that group
  • Idle chatter in unrelated groups keeps consuming your model quota

So the correct usage is: leave it off, and when a specific work or study group genuinely needs it, enable it for that one group only.

The authorization settings screen showing private-chat and group-chat policy options

The policies are set, but the gateway is still running on the old configuration — it needs a restart to take effect.

5. Restart the Gateway Service and Claim Your WeChat Account (Authorization Code) ​

After saving the authorization settings, restart the gateway to apply the policy:

bash
hermes gateway restart

Once it restarts, there's one last step: claim your own WeChat account.

  1. Find Hermes in WeChat and send it any message
  2. Hermes replies with an authorization code
  3. Enter that authorization code in the terminal to complete the binding

Once binding is done, your WeChat account is on the allowlist. From then on, when others message it, access follows the policy you set in step 4.

Hermes replying with an authorization code after a successful binding

💡 Faster allowlist route: some versions support sending /whitelist to Hermes in WeChat to add yourself to the allowlist directly, skipping the terminal step. But if you have strict security requirements around invocation permissions, manually entering the authorization code in the terminal is the more controllable option.

6. End-to-End Testing and Practical WeChat Interaction Tips ​

After binding, don't rush into adding groups — do one minimal verification first:

  1. Send Hermes an ordinary message in WeChat, like "hello"
  2. A normal reply means the whole chain works

To be more certain, check the gateway in the terminal:

bash
hermes gateway status

Once you've confirmed the gateway is running, you're good to go.

1. Practical WeChat operations and interaction scenarios ​

Connected to WeChat, Hermes handles more than ordinary Q&A — it carries the full agent capability set:

  • Daily direct-message questions and multimodal analysis: send text requests directly, or send screenshots containing tables, code, or charts and have it extract the text or analyze the key data
  • Targeted group responses (avoid burning tokens): in an authorized group, it's best for everyone to interact by @your assistant's WeChat account + the task instruction. If the group chatters a lot, non-@ conversations won't keep waking the model, which saves on API costs
  • WeChat-side control commands:
    • /whitelist: quickly claim the allowlist as an admin or friend
    • /clear or /reset: clear the current session's context memory and start a new topic
    • /help: get help on the WeChat interaction commands currently supported

Important — the gateway must stay running: the Hermes WeChat gateway needs its process online continuously to send and receive messages in real time. For long-running use on a cloud server or locally, keeping hermes gateway resident with tmux, nohup, or a background daemon is recommended, so the bot doesn't drop offline when you close the terminal window.

Looking back, the whole chain is three links, and missing any one makes it unusable:

LinkCorresponding actionWhat it does
Wiringhermes gateway setup + phone scanOpens the channel between WeChat and the gateway
RulesPrivate-chat / group-chat authorization policyDecides who can use it and in which contexts
Apply and claimhermes gateway restart + enter the authorization codeApplies the configuration and adds you to the allowlist

Sent a message but got no reply? Jump to the FAQ below and troubleshoot by symptom.

Hermes + Personal WeChat: Pros and Cons ​

Advantages

  • Low barrier: no public IP, no server to buy — a phone scan connects it
  • Ready-made entry point: WeChat is an app you already use, so there's no new interface to learn
  • Full capability: direct chat, group chat, images, video, files, and voice are all supported
  • Controllable policy: private chat and group chat are authorized separately, so strangers are blocked by default
  • Runs on your own machine: Hermes is a local service, not a cloud bot you hand your conversations to

Limitations

  • Account risk: it uses a third-party interface, and personal WeChat automation may trigger risk control — don't put your main account straight on it
  • Must stay on: the gateway has to run continuously to receive messages; shutting down or sleeping your machine breaks it
  • Coarse group boundary: group chat is controlled per group, so enabling one group hands that whole group to it and every member can issue it commands
  • Commands change between versions: this is a newer Hermes capability and subcommands may shift, so go by the output of hermes gateway --help

Who It's For and When to Use It ​

A good fit if:

  • You already use Hermes Agent and want it in WeChat, the entry point you open every day
  • You want a personal WeChat AI assistant with no public IP and no extra server
  • You're comfortable with the command line and willing to trial it on a secondary account
  • You have a regular work or project group and want an assistant to organize points and extract action items

Not a good fit if:

  • You want it for WeCom or customer-facing support: this is a third-party interface, so don't use it in production
  • You don't want to touch the command line at all
  • You have only one WeChat account and can't absorb any risk-control risk

FAQ: Missing Messages, Risk Control, and Unbinding ​

Is connecting Hermes to WeChat safe? Will it get my account banned?
Hermes uses a third-party interface (the iLink Bot API), not an official WeChat open capability, so triggering risk control is possible. The prudent approach is to run it on a secondary account you don't use much first, watch it for a while before deciding whether to move to your main account, and set private-chat authorization to DM Pairing Approval or Disable so strangers can't invoke it.
Nothing happens after scanning, or it says the QR code expired. What should I do?
QR codes expire, and the terminal reporting expiry is normal. Running hermes gateway setup again generates a new code — just scan it again with WeChat. If several attempts in a row do nothing, first confirm your phone's network is fine and WeChat itself can send and receive messages, then check the terminal for errors.
What if hermes gateway restart fails?
Run hermes gateway status first to see the gateway's current state and error. The most common cause is a port already in use — if a gateway instance is already running, stop it before restarting; if you genuinely need a different port, change the gateway port in the configuration. For the exact subcommands, go by the output of hermes gateway --help.
I sent Hermes a message in WeChat but got no reply.
Troubleshoot in three steps: first, run hermes gateway status to confirm the gateway is still running; second, check whether your WeChat account passed authorization — if private chat is set to Disable, or you haven't completed binding, you won't get a reply; third, if you sent it in a group, confirm that group's group-chat authorization has been enabled separately, since group chat is off by default.
In a group chat, why does it only respond to me and ignore others?
That's the private-chat and group-chat authorization policy at work. Group chat doesn't respond by default and has to be enabled per group; private chat defaults to DM Pairing Approval, so a stranger's first direct message needs your manual approval. Loosen the policy to open it up, or keep the default to tighten it.
Can I unbind it after binding?
Yes. Stop the gateway first (with hermes gateway stop, or the corresponding stop subcommand in hermes gateway --help) so WeChat stops responding, then delete the Hermes contact in WeChat and clear the gateway configuration.
Does it support WeCom (Enterprise WeChat)?
No. This flow targets personal WeChat accounts; WeCom is out of scope.
What can Hermes do once it's connected to WeChat?
Look things up, write summaries, translate, and generate content in direct messages; add it to a work or project group to organize meeting points and extract action items; pair it with scheduled tasks to push weather, your calendar, or RSS feeds daily; and send it images, voice messages, or files to process directly.

Related Reading

Tutorials