hermes-weixin-setup

name	hermes-weixin-setup
description	在 Hermes Agent 上安装微信 (iLink Bot API) 平台适配器，完成从依赖安装到扫码登录的全流程。一键安装，扫码即用。
category	devops

Hermes 微信 (iLink Bot API) 适配器 — 完整安装指南

适用场景: 用户需要在 Hermes Agent 上接入微信个人账号，实现 AI 自动收发消息 协议: iLink Bot API (微信官方开放协议) 适配器: weixin.py (见附件 references/weixin.py) 预计耗时: 5-10 分钟（含扫码等待） 分享说明: 本 skill 可直接分享给其他 Hermes 用户，包含完整代码和流程

---

快速开始（给用户的引导话术）

当用户说「我要接微信」或「配置微信渠道」时，按以下流程引导：

Phase 1: 环境检查

我来帮你接入微信渠道。先检查一下环境...

执行以下检查：

# 1. 检查 Hermes 是否存在
ls ~/.hermes/hermes-agent/gateway/platforms/ 2>/dev/null && echo "OK" || echo "MISSING"

# 2. 检查 Python 版本
python3 --version

# 3. 检查 uv 是否可用
which uv && uv --version

如果任何检查失败，告知用户需要先安装缺失的工具。

Phase 2: 安装依赖

cd ~/.hermes/hermes-agent
uv add aiohttp cryptography qrcode pillow

Phase 3: 部署适配器文件

关键步骤: 将 references/weixin.py 复制到 Hermes 平台目录：

cp <skill-path>/references/weixin.py ~/.hermes/hermes-agent/gateway/platforms/weixin.py

其中 <skill-path> 是本 skill 的安装路径，通常在 ~/.hermes/skills/devops/hermes-weixin-setup/

Phase 4: Patch Hermes 核心文件

4a. 在 gateway/config.py 添加 WEIXIN 枚举

找到 Platform 枚举，在 WECOM = "wecom" 之后添加：

WEIXIN = "weixin",

4b. 在 gateway/run.py 注册适配器工厂

找到 _create_adapter() 方法中的 WECOM 分支，在其后添加：

elif platform == Platform.WEIXIN:
    from gateway.platforms.weixin import WeixinAdapter, check_weixin_requirements
    if not check_weixin_requirements():
        logger.warning("WeChat: aiohttp/cryptography not installed")
        return None
    return WeixinAdapter(config)

Phase 5: 扫码登录（交互式核心）⭐

这是最关键的步骤。告诉用户：

接下来需要你用微信扫码登录。我会启动登录进程，
生成二维码给你扫描。请准备好你的手机微信。

方式 A：Agent 后台执行（推荐）

生成并运行登录脚本：

cat > /tmp/weixin-login.py << 'PYEOF'
import asyncio, json, sys, os
sys.path.insert(0, os.path.expanduser("~/.hermes/hermes-agent"))
from gateway.platforms.weixin import qr_login

result = asyncio.run(qr_login(os.path.expanduser("~/.hermes")))
if result:
    out = "/tmp/weixin_login_result.json"
    with open(out, "w") as f:
        json.dump(result, f, indent=2)
    print(f"\n=== 登录成功！信息已保存到 {out} ===")
    print(json.dumps(result, indent=2))
else:
    print("\n=== 登录失败 ===")
    sys.exit(1)
PYEOF

cd ~/.hermes/hermes-agent && .venv/bin/python /tmp/weixin-login.py

重要提示：

• 必须使用 background=true 运行此命令（因为扫码需要时间）
• 用 process(action="poll") 监控进度
• 当用户看到二维码 URL 后，提醒他用手机微信扫一扫

方式 B：备用方案（如果用户看不到二维码）

如果后台运行导致用户无法看到二维码输出，告诉用户：

⚠️ 看起来终端输出被拦截了，无法显示二维码。
没关系，请按以下步骤操作：

1. 打开一个新的终端窗口（Terminal / CMD）
2. 复制粘贴以下命令并回车执行：
【粘贴单行登录脚本】
3. 终端会显示二维码 URL，用手机微信扫一扫并在微信内确认
4. 登录成功后，把终端输出的 JSON 内容复制发给我

单行登录脚本（让用户复制）：

cd ~/.hermes/hermes-agent && .venv/bin/python -c "import asyncio,json,sys,os; sys.path.insert(0,'.'); from gateway.platforms.weixin import qr_login; r=asyncio.run(qr_login(os.path.expanduser('~/.hermes'))); open('/tmp/weixin_login_result.json','w').write(json.dumps(r,indent=2)) if r else sys.exit(1); print(json.dumps(r,indent=2))"

用户把 JSON 发回来后，继续 Phase 6 写入配置。

扫码后的状态流转：

1. wait → 等待扫码（显示 .）
2. scaned → 已扫码，等确认（显示 👀 已扫码，请在微信中确认...）
3. confirmed → 登录成功！（显示 ✅ 微信连接成功！）
4. expired → 二维码过期，自动刷新（最多 3 次）

Phase 6: 写入配置

登录成功后，读取结果并写入 config.yaml：

cat /tmp/weixin_login_result.json

输出示例：

{
  "account_id": "o9cq80yecxZhQHeAnocHatgkk_lo",
  "token": "xxxxxxxxxxxxxxx",
  "base_url": "https://ilinkai.weixin.qq.com",
  "user_id": "o9cq80yecxZhQHeAnocHatgkk_lo"
}

写入 ~/.hermes/config.yaml：

在 platforms: 下添加：

platforms:
  weixin:
    enabled: true
    extra:
      account_id: "<从登录结果获取>"
      token: "<从登录结果获取>"
      base_url: "https://ilinkai.weixin.qq.com"
      dm_policy: "open"          # open | allowlist | pairing
      allow_from: []
    home_channel:
      platform: "weixin"
      chat_id: "<user_id 从登录结果获取>"   # 如 [e-mail]

在 platform_toolsets: 下添加：

platform_toolsets:
  # ... 其他平台 ...
  weixin:
  - hermes-cli

在 ~/.hermes/.env 中添加：

GATEWAY_ALLOW_ALL_USERS=true

Phase 7: 询问重启 ⭐

配置写入完成后，询问用户：

✅ 微信配置已完成！

配置摘要：
- account_id: xxxxxxxx
- dm_policy: open（允许所有人私聊）
- home_channel: 已设置

是否需要我现在重启网关以激活微信连接？
回复「重启」或「yes」我将立即重启。

如果用户确认重启：

# 停止现有网关（如果在运行）
pkill -f "hermes gateway" 2>/dev/null || true

# 启动网关
cd ~/.hermes/hermes-agent && hermes gateway run

Phase 8: 验证连接

重启后，检查日志确认微信连接成功：

grep -i "weixin" ~/.hermes/logs/gateway.log | tail -15

期望看到的日志：

weixin: adapter connected (account=xxxxxxxx, base=https://ilinkai.weixin.qq.com)
weixin: starting poll loop (account=xxxxxxxx)
weixin: inbound from=xxxxxxxx text_len=xx images=0

最终验证：让用户用另一个微信号给该账号发一条消息，看 AI 是否自动回复。

---

完整安装脚本（一键版）

如果想一步到位，可以用这个完整脚本：

#!/bin/bash
set -e

HERMES_HOME="$HOME/.hermes"
HERMES_AGENT="$HERMES_HOME/hermes-agent"
PLATFORM_DIR="$HERMES_AGENT/gateway/platforms"

echo "=== Hermes 微信适配器一键安装 ==="

# Step 1: 检查环境
echo "[1/7] 检查环境..."
[ -d "$PLATFORM_DIR" ] || { echo "ERROR: Hermes 未安装在 $HERMES_AGENT"; exit 1; }
command -v uv >/dev/null 2>&1 || { echo "ERROR: uv 未安装"; exit 1; }
echo "✓ 环境检查通过"

# Step 2: 安装依赖
echo "[2/7] 安装 Python 依赖..."
cd "$HERMES_AGENT"
uv add aiohttp cryptography qrcode pillow 2>&1 | tail -3
echo "✓ 依赖安装完成"

# Step 3: 复制适配器（需要提前把 weixin.py 放好）
echo "[3/7] 部署适配器..."
SKILL_DIR="$HERMES_HOME/skills/devops/hermes-weixin-setup/references"
if [ -f "$SKILL_DIR/weixin.py" ]; then
    cp "$SKILL_DIR/weixin.py" "$PLATFORM_DIR/weixin.py"
    echo "✓ 适配器已部署"
else
    echo "⚠ 请手动复制 weixin.py 到 $PLATFORM_DIR/"
fi

# Step 4-6: 需要 Agent 执行 patch 和配置
echo ""
echo "[4-6/7] Patch 和配置需要 Agent 辅助完成..."
echo "请继续与 Agent 对话，它会帮你："
echo "  - Patch gateway/config.py (添加 WEIXIN 枚举)"
echo "  - Patch gateway/run.py (注册适配器工厂)"
echo "  - 引导你扫码登录"
echo "  - 写入 config.yaml 配置"
echo ""
echo "或者运行 /tmp/weixin-login.py 开始扫码登录"
echo "=== 一键安装脚本结束 ==="

---

已知问题 & 解决方案（踩坑手册）

坑 1: get_hermes_dir() 签名不匹配

症状: 启动时报 TypeError: get_hermes_dir() missing 2 required positional arguments 原因: 当前版 Hermes 的 get_hermes_dir(new_subpath, old_name) 需要 2 个参数 修复: 本适配器已使用 get_hermes_home() 替代（无参数版本），无需额外处理

坑 2: 登录命令被中断

症状: 前台跑 qr_login 时用户发新消息导致进程被 kill (exit code 130) 修复: 使用 background=true 启动登录进程，通过 process poll 等待结果

坑 3: MessageEvent 字段名错误 ⚠️ 最常见

症状: 微信发消息后报错：TypeError: MessageEvent.__init__() got an unexpected keyword argument 'content' 原因: 旧版用了 content=text，但正确字段是 text 修复: 本适配器已修复（第 1045-1050 行），使用正确的字段名：

event = MessageEvent(
    source=source,
    text=text,                    # ✓ 正确
    message_type=MessageType.IMAGE if images else MessageType.TEXT,
    message_id=str(msg_id) if msg_id else None,
)

坑 4: KeyError 'weixin' — platform_toolsets 未配置

症状: 微信消息能收到但 agent 回复报错：KeyError: 'weixin' 原因: config.yaml 中 platform_toolsets 没有 weixin 条目 修复: 添加（见 Phase 6）

坑 5: No home channel for Weixin

症状: 回复提示 "No home channel is set for Weixin" 原因: weixin 平台配置中没有设置 home_channel 修复: 添加 home_channel（见 Phase 6）

坑 6: 用户被拒绝访问

症状: 日志显示 "No user allowlists configured. All unauthorized users will be denied." 原因: 默认需要用户白名单 修复: 设置 GATEWAY_ALLOW_ALL_USERS=true（见 Phase 6）

坑 7: 二维码过期

症状: 扫码太慢导致二维码过期 修复: 适配器会自动刷新二维码（最多 3 次），过期后会打印新的二维码 URL

坑 8: 会话过期 (errcode=-14)

症状: 日志出现 "session expired, pausing 10 min" 原因: token 过期或服务端会话失效 修复: 适配器会自动暂停 10 分钟后重试；如持续失败需重新扫码登录

---

文件变更清单

文件	操作	说明
gateway/platforms/weixin.py	新增	适配器主文件（1275 行）
gateway/config.py	修改	加 WEIXIN = "weixin" 枚举值
gateway/run.py	修改	注册 WeixinAdapter 工厂函数
~/.hermes/config.yaml	修改	加 platforms.weixin + platform_toolsets + home_channel
~/.hermes/.env	修改	加 GATEWAY_ALLOW_ALL_USERS=true
pyproject.toml / uv.lock	修改	uv add 自动更新

---

验证 Checklist

安装完成后，逐项确认：

• uv list 显示 aiohttp, cryptography, qrcode, pillow 已安装
• gateway/platforms/weixin.py 存在且可 import
• gateway/config.py 的 Platform 枚举包含 WEIXIN
• gateway/run.py 的 _create_adapter() 有 WEIXIN 分支
• config.yaml 有完整的 platforms.weixin 配置
• .env 有 GATEWAY_ALLOW_ALL_USERS=true
• 网关启动无报错
• 日志出现 weixin: adapter connected
• 日志出现 weixin: starting poll loop
• 微信发消息后有 weixin: inbound from= 日志（无 TypeError）
• agent 能正常回复微信消息（无 KeyError / No home channel 错误）

全部勾选 ✅ 即表示安装成功！

---

卸载指南

如需移除微信适配器：

# 1. 删除适配器文件
rm ~/.hermes/hermes-agent/gateway/platforms/weixin.py

# 2. 移除 config.yaml 中的 weixin 相关配置
# （手动编辑或让 Agent 帮忙）

# 3. 重启网关

---

技术架构说明

消息流

微信 ←→ iLink API ←→ weixin.py (长轮询) ←→ Hermes Gateway ←→ AI Agent

核心功能

• 消息接收: Long-polling getUpdates 循环（35s 超时）
• 消息发送: sendMessage API + context_token 回显
• 媒体上传: AES-128-ECB 加密 → CDN 上传 → 发送引用
• 图片下载: 下载并缓存到本地
• 语音转文字: 使用微信内置的 voice_item.text
• 引用消息: 提取 ref_msg 上下文拼接
• 去重: 基于 message_id 的 5 分钟窗口去重
• 权限控制: open / allowlist / pairing 三种 DM 策略

协议常量

• Base URL: https://ilinkai.weixin.qq.com
• CDN URL: https://novac2c.cdn.weixin.qq.com/c2c
• Channel Version: 2.1.3
• Poll Timeout: 35000ms
• Max Consecutive Failures: 3（之后 backoff 30s）