Hermes WeChat Adapter

扫码关注公众号「铁柱AGI」 获取更多 Hermes / OpenClaw / AI Agent 实战教程与前沿动态

---

快速开始 • 功能特性 • 安装步骤 • 已知限制 • 常见问题

---

关于本项目

Hermes WeChat Adapter 是一个为 Hermes Agent 开发的微信个人号接入适配器，基于 iLink Bot API（微信官方开放协议）实现。

这个项目由 Hermes Agent 自己编写、整理并提交到仓库。 从代码开发到文档撰写再到 Git 提交，全部由 AI 自主完成。

为什么需要这个项目？

Hermes 原生支持 Telegram、Discord、Slack 等多个消息平台，但不支持微信。而微信是中国最主流的即时通讯工具，对于中文用户来说，无法接入微信意味着失去了最重要的 AI 交互入口。

本项目填补了这个空白。

---

工作原理

架构总览

┌─────────────┐     ┌──────────────────┐     ┌─────────────────┐     ┌──────────┐
│   微信 App   │ ←→  │  iLink Bot API   │ ←→  │   weixin.py     │ ←→  │  Hermes  │
│  (你的手机)  │     │ (微信官方协议)    │     │  (本适配器)      │     │ Gateway  │
└─────────────┘     └──────────────────┘     └─────────────────┘     └──────────┘
                            ↓                        ↓                      ↓
                     https://ilinkai          长轮询 getUpdates         AI Agent
                     ..weixin.qq.com          sendMessage              自动回复

核心机制

消息流转过程

1. 接收消息: weixin.py 以长轮询方式调用 getUpdates 接口
2. 解析内容: 提取文本、图片、语音、文件等，处理引用消息
3. 媒体下载: AES 解密 CDN 数据 → 缓存到本地 → 交给 Agent
4. 派发给 Hermes: 封装成 MessageEvent 交给 Gateway 调度
5. AI 处理: Agent 思考并生成回复
6. 发送回复: 通过 sendMessage 接口将结果发回微信

---

功能特性

✅ 已完整实现

⚠️ 基础实现（能用但有局限）

❌ 不支持（协议或平台限制）

以下功能当前版本无法实现，原因标注在每项后面。不排除未来 iLink 协议升级或 Hermes 架构变化后可能支持。

---

快速开始

前置要求

• Hermes Agent 已安装运行
• Python 3.10+
• uv 包管理器
• 一个微信个人号（用于扫码登录）

给 Hermes Agent 的指令

把下面这段话发给你的 Hermes Agent，它会自动完成全部安装流程：

请帮我安装微信渠道适配器。

从 GitHub 克隆这个项目：
git clone [email protected]:RongleCat/hermes-wechat.git /tmp/hermes-wechat

然后读取 SKILL.md，按照里面的完整流程（8 个 Phase）逐步执行，
包括环境检查、依赖安装、适配器部署、核心文件 Patch、扫码登录、
配置写入、重启网关、连接验证。

---

安装步骤

Step 1: 克隆项目

git clone [email protected]:RongleCat/hermes-wechat.git /tmp/hermes-wechat
cd /tmp/hermes-wechat

Step 2: 安装 Python 依赖

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

Step 3: 部署适配器

cp /tmp/hermes-wechat/references/weixin.py \
   ~/.hermes/hermes-agent/gateway/platforms/weixin.py

Step 4: Patch Hermes 核心

4a. 编辑 ~/.hermes/hermes-agent/gateway/config.py

在 Platform 枚举的 WECOM = "wecom" 之后添加：

WEIXIN = "weixin",

4b. 编辑 ~/.hermes/hermes-agent/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: deps missing")
        return None
    return WeixinAdapter(config)

Step 5: 扫码登录

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

终端会显示 ASCII 二维码，用手机微信扫描并在微信内确认登录。

Step 6: 写入配置

登录成功后，编辑 ~/.hermes/config.yaml，添加：

platforms:
  weixin:
    enabled: true
    extra:
      account_id: "从登录结果获取"
      token: "从登录结果获取"
      base_url: "https://ilinkai.weixin.qq.com"
      dm_policy: "open"
      allow_from: []
    home_channel:
      platform: "weixin"
      chat_id: "从登录结果获取"

platform_toolsets:
  weixin:
  - hermes-cli

在 ~/.hermes/.env 添加：

GATEWAY_ALLOW_ALL_USERS=true

Step 7: 重启网关

hermes gateway restart

Step 8: 验证

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

看到以下日志即表示成功：

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

---

常见问题

---

项目结构

hermes-wechat/
├── README.md                  # 本文件 - 项目介绍与安装指南
├── SKILL.md                   # Hermes Skill 定义 - Agent 执行指南
├── LICENSE                    # MIT 开源协议
├── .gitignore                 # Git 忽略规则
├── references/
│   └── weixin.py             # 微信适配器源码 (1488 行, v2.1.5)
└── images/
    └── qrcode.png            # 公众号二维码

---

版本历史

---

License

MIT © 2026 RongleCat

---

Made with ❤️ by RongleCat & Hermes Agent This repository was written, organized and committed by Hermes Agent itself.