前置条件
- 个人微信账号（已实名）
- 能访问微信 API 的网络环境（Hermes 所在服务器需能连接 iLink 平台）
- Hermes Agent 已安装且能正常运行
微信配置所需参数（快速获取）
配置 Hermes 连接个人微信有两种方式，二选一即可：
方式 A：hermes setup wechat 扫码（推荐 ⭐）
Hermes 内置了自动化注册流程，扫码即可完成全部配置：
# 终端执行
hermes setup wechat
# 终端会显示一个二维码 → 用微信扫码
# 扫码后自动在 iLink 平台注册 Bot
# 自动写入 .env 配置
# 自动启动 Gateway
不需要手动去任何网站注册。 扫码 → Hermes 自动完成全部步骤。
| # | 自动完成的内容 | 对应 .env 变量 |
|---|---|---|
| ① | 自动在 iLink 平台注册 Bot 账号 | — |
| ② | 自动生成并写入 Bot Token | WEIXIN_TOKEN |
| ③ | 自动获取并写入 Account ID | WEIXIN_ACCOUNT_ID |
| ④ | 自动启动 Gateway 并开始轮询消息 | — |
方式 B：微信开发者平台手动注册
如果不想用自动扫码流程，也可以手动在 iLink 平台注册：
- 浏览器打开 ilinkai.weixin.qq.com
- 使用微信扫码登录
- 在控制台创建 Bot → 获得以下两个值：
| # | 配置项 | .env 变量 | 获取方式 | 必填 |
|---|---|---|---|---|
| ① | Bot Token | WEIXIN_TOKEN |
iLink 控制台 → Bot 详情 → Token | ✅ |
| ② | Account ID | WEIXIN_ACCOUNT_ID |
iLink 控制台 → Bot 详情 → Account ID | ✅ |
完整 .env 配置（实际调试通过）
以下配置已在真实环境验证，扫码注册后微调即可使用：
# ========== 微信 WeChat - 凭证（必填） ==========
WEIXIN_TOKEN=your_bot_token
WEIXIN_ACCOUNT_ID=your_account_id
# ========== 微信 WeChat - 权限控制（重要） ==========
WEIXIN_DM_POLICY=open # 放开私聊限制
WEIXIN_ALLOW_ALL_USERS=true # 允许所有人私聊（配合 open 使用）
# WEIXIN_ALLOWED_USERS=wxid_xxx # 如不开全部，用白名单指定
WEIXIN_GROUP_POLICY=disabled # ⚠️ 群聊不可用，必须关掉
# ========== 微信 WeChat - 连接配置（可选） ==========
# WEIXIN_BASE_URL=https://ilinkai.weixin.qq.com
# WEIXIN_CDN_BASE_URL=https://novac2c.cdn.weixin.qq.com/c2c
# ========== 微信 WeChat - 消息调优（可选） ==========
# WEIXIN_SPLIT_MULTILINE_MESSAGES=true
# WEIXIN_SEND_CHUNK_DELAY_SECONDS=1.5
# WEIXIN_SEND_CHUNK_RETRIES=4
配置写入 /opt/data/.env 后重启容器生效。
架构示意图
架构说明
- 用户入口 — 微信中私聊 Bot 对话窗口（群聊不可用，见下方说明）
- iLink 平台 — 腾讯官方的微信 Bot 网关，Bot 通过 QR 扫码登录后，Long-Polling 轮询新消息
- WeChat Adapter — 接收消息、解析格式、DM Policy 权限校验、去重
- Gateway Core — 路由消息到正确 Session，管理上下文
- Agent Core — LLM 处理 + Tools 执行 + Skills 调用，生成回复
- 回复路径 — 回复走 iLink 发送 API 返回微信
使用生命周期
阶段一：注册与配置
- 执行
hermes setup wechat→ 扫码 → 自动完成注册和配置 - 在
/opt/data/.env中添加权限控制变量（见上方完整配置） - 重启容器使配置生效
- 验证：微信中搜索 Bot 名称 → 发任意消息 → Hermes 回复
阶段二：私聊
- 微信好友在「通讯录」中搜索 Bot 名称（即注册时设置的应用名）
- 进入 Bot 对话窗口，直接发送消息
- Hermes 实时回复，上下文连续
- 支持文字、图片、文件
- 用
/new重置会话，/model切换模型
阶段三：⚠️ 群聊不可用（iLink 平台限制）
iLink 注册的 Bot 账号身份是 xxx@im.bot，这是机器人账号：
- 无法被拉入普通微信群 — 只有普通微信号能加群
- iLink 不推送群事件 — 即使配置
WEIXIN_GROUP_POLICY=open，群消息也永远不会到达 Hermes - 因此
WEIXIN_GROUP_POLICY必须设为disabled，否则日志中会出现误导性的警告
阶段四：权限校验要点（踩坑记录）
Hermes 的 WeChat Adapter 使用两层权限判断，必须同时正确设置：
| 变量 | 值 | 说明 |
|---|---|---|
WEIXIN_DM_POLICY |
open |
策略层：允许私聊 |
WEIXIN_ALLOW_ALL_USERS |
true |
用户层：放行所有用户（否则即使 policy=open 也会被白名单拒绝） |
如果缺了后者，日志会出现：
WARNING gateway.run: Unauthorized user: xxx@im.wechat on weixin
阶段五：管理维护
- 保持在线 — iLink Bot 需通过 QR 扫码保持登录，掉线后重新
hermes setup wechat - Token 轮换 — iLink 控制台重新生成 Token，更新 .env 后重启
- Session 清理 —
/new重置，日志自动清理过期上下文 - /platforms — 查看微信 Bot 连接状态
日常使用场景
📋 私聊 — 微信随身助手
| 场景 | 示例 |
|---|---|
| 快速问答 | 「最近有什么好电影推荐？」→ Hermes 直接回答 |
| 文案生成 | 「帮我写一段今天的朋友圈文案，关于周末露营的」 |
| 翻译润色 | 「这段中文帮我翻译成英文，正式一点」 |
| 文件处理 | 发一个 PDF/Word → 「帮我提取摘要」→ 微信里完成 |
| 技术问答 | 「Python 怎么用 async/await 处理并发？」 |
| 代办清单 | 「帮我列一下周末要做的事情」 |
| 图片分析 | 发一张照片 → 「这个植物是什么品种？」（需 vision 能力） |
📋 不适合的场景
| 场景 | 原因 | 替代方案 |
|---|---|---|
| 群聊多任务管理 | iLink Bot 无法加群 | 使用 Telegram Group + Topics |
| 团队协作机器人 | 个人微信 Bot 只能你自己用 | 使用飞书/企业微信 |
| Cron 定时推送仪表盘 | 微信没有 Topic 机制 | 使用 Telegram（deliver 到指定 Topic） |
调试与排错
常见 Warning 及处理
| Warning | 原因 | 解决 |
|---|---|---|
Unauthorized user: xxx@im.wechat on weixin |
DM Policy 或 ALLOW_ALL_USERS 未放行 | 设 WEIXIN_DM_POLICY=open + WEIXIN_ALLOW_ALL_USERS=true |
WEIXIN_GROUP_POLICY=open is set, but QR-login connects an iLink bot... |
iLink Bot 无法参与群聊 | 设 WEIXIN_GROUP_POLICY=disabled |
Connected to ws://xxx... OK |
✅ 正常连接 | 无 |
消息发出去 Bot 不回复
- 检查 Gateway 日志：
tail -f ~/.hermes/logs/gateway.log | grep weixin - 确认 .env 中
WEIXIN_DM_POLICY=open+WEIXIN_ALLOW_ALL_USERS=true - 确认 Bot 在线（iLink 控制台可看到连接状态）
- 重启 Gateway 后重试
常用命令速查
| 命令 | 说明 |
|---|---|
/help | 查看所有 Hermes 命令 |
/new | 重置当前会话 |
/title <name> | 命名当前会话 |
/retry | 重新生成回复 |
/undo | 撤回上一轮 |
/model <name> | 切换模型 |
/status | 查看会话状态 |
/platforms | 查看所有平台连接状态 |