Connect Hermes to Weixin with QR Authentication

The Weixin adapter uses a QR-based login flow and stores account credentials under the Hermes home directory. This makes initial setup convenient, but it also turns local account files and QR handling into security-sensitive operational state.

Official documentation: https://hermes-agent.nousresearch.com/docs/user-guide/messaging/weixin

Protect the login ceremony

Run hermes gateway setup on a trusted terminal and select Weixin. The wizard requests a QR code, waits for a scan and phone confirmation, and saves the account credentials locally. Do not share the QR image, copy the resulting token into chat, or include the account directory in a public backup.

Restrict access to intended users and groups. Choose a home target for notifications only after confirming its stable identifier and audience. If multiple Weixin accounts are involved, name and document them clearly to avoid sending from the wrong identity.

Setup checklist

• Use a private terminal for the QR login flow.
• Scan and confirm with the intended Weixin account.
• Verify account state is stored under the expected Hermes profile.
• Configure allowed users or groups.
• Decide whether multiline messages should be split.
• Set a fixed home target for scheduled delivery if needed.
• Start the gateway and inspect adapter readiness.
• Exclude account credentials from public backups and support bundles.

Plan for account lifecycle

QR-authenticated sessions can expire or be revoked. Document how to recognize an authentication failure, re-run setup, and verify the account identity after reauthentication. Do not repeatedly scan new logins without understanding whether stale account records remain.

Message formatting also deserves testing. Multiline splitting can change readability and increase the number of delivered messages. Keep it disabled unless a real client behavior requires it, then verify rate limits and ordering.

Common pitfalls

• Capturing the QR code in a screenshot, livestream, or support ticket.
• Mixing credentials between Hermes profiles.
• Treating local account files as ordinary cache data.
• Enabling multiline splitting without testing message ordering.
• Using the last active chat as an implicit cron destination.
• Reauthenticating repeatedly without cleaning up or identifying stale sessions.

Verification steps

1. Complete QR login and confirm the adapter identifies the intended account.
2. Send a direct message from an allowed identity and verify one reply.
3. Test an unauthorized sender or group according to policy.
4. Send a multiline prompt and inspect the exact outbound formatting.
5. Restart the gateway and verify the account resumes without another login when expected.
6. Revoke a test session or simulate expiry and verify the recovery instructions.
7. Scan logs and backup manifests for QR images, tokens, account files, and unintended message content.