Problem

When running hermes gateway setup and selecting WeChat (Weixin) as a messaging platform, users encounter the error:

（终端二维码渲染失败，请直接打开上面的二维码链接）

This happens because the qrcode package is not installed by default.

Root Cause

The qrcode package is not declared as a dependency in pyproject.toml:

[project.optional-dependencies]
messaging = ["python-telegram-bot[webhooks]>=22.6,<23", "discord.py[voice]>=2.7.1,<3", "aiohttp>=3.13.3,<4", "slack-bolt>=1.18.0,<2", "slack-sdk>=3.27.0,<4"]

Users who install via pip install hermes-agent[messaging] don't get the qrcode package, even though it's used by the Weixin QR login flow.

Comparison with Similar Projects

OpenClaw's Feishu plugin explicitly declares qrcode-terminal as a dependency in package.json:

"dependencies": {
  "qrcode-terminal": "^0.12.0"
}

This ensures QR codes render correctly in the terminal without user intervention.

Proposed Solution

Add qrcode to the messaging optional dependencies:

[project.optional-dependencies]
messaging = [..., "qrcode>=7.0,<8"]

Benefits

1. Better UX: Users installing hermes-agent[messaging] get terminal QR rendering automatically
2. Consistency: Matches the behavior of other messaging platforms that have setup flows
3. Small overhead: The qrcode package is lightweight (~50KB) with no heavy dependencies

Alternative

If adding qrcode to messaging is not desired, we could:

1. Create a new weixin extra: pip install hermes-agent[messaging,weixin]
2. Keep the current behavior but improve the error message to suggest pip install qrcode

Related

• File: gateway/platforms/weixin.py:959-967
• Docs: website/docs/user-guide/messaging/weixin.md