夜雨聆风> 不是 hook，不走灰色，腾讯官方 iLink Bot API，扫码即用。
-----
## 为什么这次不一样？
市面上的微信AI方案，要么是 hook 注入（封号风险极高），要么是企业微信（需要公司主体），要么走第三方模拟协议（随时被封）。
**Hermes Agent 的微信适配器走的是腾讯官方 iLink Bot API**，这是 Tencent 为个人微信账号提供的机器人接入通道，不依赖 hook、不需要公网 IP、不需要 Webhook，纯长轮询即可跑起来。
-----
## 能做什么？
|功能 |说明 |
|-----------|------------------|
|私聊自动回复 |开放/白名单/禁用，策略自由配置 |
|群聊智能接管 |默认关闭，可按群 ID 白名单开启 |
|图片/视频/文件 |全支持，走微信 CDN 自动加解密 |
|语音消息 |自动提取文字转写，有转写就用文字 |
|长消息自动拆分 |按段落/代码块边界智能断句，不乱 |
|Markdown 渲染|表格、标题、代码块自动转微信格式 |
|“正在输入…” 状态 |AI思考期间显示输入状态，体验更自然|
|重启不丢上下文 |会话 token 持久化存盘 |
-----
## 前置条件
- 一台能跑 Python 的机器（云服务器、Mac、Linux 均可）
- 一个个人微信账号（手机正常在线）
- 已安装 Python 3.10+
> ⚠️ 这套方案针对**个人微信**。企业微信（WeCom）是另一个适配器，不要搞混。
-----
## 第一步：安装 Hermes Agent
```bash
pip install hermes-agent
```
安装微信适配器所需依赖：
```bash
pip install aiohttp cryptography
# 可选：终端内直接显示二维码（推荐装上）
pip install qrcode
```
-----
## 第二步：扫码登录微信
运行配置向导：
```bash
hermes gateway setup
```
按提示选择 **Weixin**，接下来它会：
1. 向 iLink Bot API 请求二维码
1. 在终端显示二维码（或给出扫码链接）
1. 用微信手机扫描该二维码
1. 手机上点击**确认登录**
1. 自动保存凭证到 `~/.hermes/weixin/accounts/`
登录成功后终端会显示：
```
微信连接成功，account_id=xxxxxxxx
```
凭证（account_id / token / base_url）全部自动保存，无需手动填写。
-----
## 第三步：配置环境变量
编辑 `~/.hermes/.env`，至少填入：
```env
WEIXIN_ACCOUNT_ID=你的account_id
# 私聊策略：open（所有人）/ allowlist（白名单）/ disabled（关闭）
WEIXIN_DM_POLICY=open
# 可选：白名单用户（dm_policy=allowlist 时生效）
# WEIXIN_ALLOWED_USERS=user_id_1,user_id_2
# 可选：指定一个"主频道"用于接收通知/定时任务
# WEIXIN_HOME_CHANNEL=某个chat_id
```
群聊默认是**关闭**的（`group_policy=disabled`），如需开启：
```env
WEIXIN_GROUP_POLICY=allowlist
WEIXIN_GROUP_ALLOWED_USERS=群ID_1,群ID_2
```
> 💡 个人微信群聊默认关闭是故意的——毕竟你可能加了几百个群，不能乱回。
-----
## 第四步：启动网关
```bash
hermes gateway
```
启动后 Hermes 会自动恢复登录凭证、连接 iLink API，开始长轮询消息。**不需要公网 IP，不需要端口映射**，国内网络直连。
-----
## 进阶：后台运行（服务器推荐）
如果你和我一样把它跑在云服务器上，建议用 `nohup` 或 `systemd` 守护：
```bash
# 简单方式
nohup hermes gateway > ~/hermes_weixin.log 2>&1 &
# 查看日志
tail -f ~/hermes_weixin.log
```
-----
## 媒体消息的安全细节
微信的媒体文件走的是加密 CDN（AES-128-ECB），Hermes 会自动处理：
- **收到图片/视频/文件**：从 CDN 下载 → 自动解密 → 本地缓存供 AI 处理
- **发出文件**：本地加密 → 上传 CDN → 发送加密引用
整个过程对用户完全透明，这也是为什么需要安装 `cryptography` 包。
-----
## 常见问题
**Q：会不会封号？**
A：iLink Bot API 是腾讯官方通道，理论上比 hook 方案安全得多。但任何自动化都存在一定风险，建议用小号先试，不要用主力微信直接上。
**Q：需要手机一直在线吗？**
A：是的，微信扫码登录后手机需保持正常在线状态，类似网页版微信的逻辑。
**Q：AI 用哪个模型？**
A：Hermes Agent 支持接入 OpenAI、Claude、DeepSeek 等主流模型，在 `~/.hermes/config.yaml` 中配置即可。
**Q：和企业微信（WeCom）什么区别？**
A：完全不同的产品线。WeCom 需要企业主体认证，消息能力更强但门槛高；Weixin 就是普通个人微信，扫码即用。
-----
## 项目地址
- 官方文档：https://hermes-agent.nousresearch.com/docs/user-guide/messaging/weixin
- GitHub：https://github.com/NousResearch/hermes-agent
- Discord 社区：https://discord.gg/NousResearch
-----
*个人微信 × AI 自动化，这条路终于走通了。有问题欢迎留言，我会持续跟进。*
