Hermes Agent 微信对接

Hermes Agent 微信对接部署指南

引言

随着 AI 智能体的兴起，开发者们正在探索将大语言模型能力接入各种即时通讯平台。微信作为中国最大的社交平台，拥有超过 13 亿月活跃用户，将其与 AI 助手打通，能够为个人和企业带来巨大的效率提升。

Hermes Agent 是一款功能强大的开源自动化代理框架，支持通过插件系统无缝对接多种外部服务。本文将手把手教你如何将 Hermes Agent 与微信对接，让你的 AI 助手在微信上随时待命。

前置条件
– 已安装并运行 Hermes Agent（版本 ≥ 0.1.0）
– 拥有一台可用的 Linux 服务器（推荐 Ubuntu 22.04+）
– 具备基础的命令行操作能力

一、理解微信对接架构

在开始部署之前，我们需要先了解整体架构。Hermes Agent 采用模块化设计，微信对接通过插件机制实现解耦：

┌─────────────┐      ┌──────────────┐      ┌─────────────┐
│   微信用户    │ ───▶ │ Hermes Agent  │ ───▶ │  大模型 API  │
│  (手机端)     │ ◀─── │   (服务端)    │ ◀─── │ (OpenAI等)  │
└─────────────┘      └──────────────┘      └─────────────┘
                            │
                     ┌──────────────┐
                     │  SQLite 数据库 │
                     │  (记忆存储)    │
                     └──────────────┘

核心通信流程如下：

步骤	方向	说明
1	用户 → Agent	用户在微信发送消息
2	Agent → LLM	Agent 将消息转发给大模型
3	LLM → Agent	大模型返回生成的回复
4	Agent → 用户	Agent 通过微信接口推送回复

这种架构的优势在于：逻辑与传输层完全分离。你可以轻松替换底层的大模型提供商，或者扩展到其他平台（Telegram、Discord 等），而无需改动核心业务逻辑。

二、环境准备

2.1 安装依赖

首先确保你的服务器上安装了必要的依赖包：

# 更新系统包
sudo apt update && sudo apt upgrade -y

# 安装 Python 3.10+（如尚未安装）
sudo apt install python3.10 python3.10-venv python3-pip -y

# 安装其他必要工具
sudo apt install git curl wget -y

2.2 配置大模型 API Key

Hermes Agent 支持 OpenAI 兼容的 API，你可以根据自己的需求选择提供商。以下是常用选项：

提供商	API Base	价格参考
OpenAI	`https://api.openai.com/v1`	~$0.01/1K tokens
智谱 AI	`https://open.bigmodel.cn/api/paas/v4`	~¥0.005/1K tokens
通义千问	`https://dashscope.aliyuncs.com/compatible-mode/v1`	~¥0.003/1K tokens

设置 API Key 环境变量：

# 编辑环境变量文件
echo 'export OPENAI_API_KEY="sk-your-api-key-here"' >> ~/.bashrc
source ~/.bashrc

# 可选：自定义 API Base
echo 'export OPENAI_API_BASE="https://your-custom-base.com/v1"' >> ~/.bashrc
source ~/.bashrc

三、配置微信插件

3.1 获取 Hermes Agent 微信插件

克隆官方仓库或从插件市场安装：

cd /usr/local/lib/hermes-agent
git clone https://github.com/NousResearch/hermes-wechat-plugin.git plugins/wechat

3.2 修改配置文件

进入插件目录并复制默认配置模板：

cp plugins/wechat/config.example.yaml plugins/wechat/config.yaml

使用编辑器打开 config.yaml，进行以下关键配置：

# ========== 微信插件配置 ==========
wechat:
  # 模式选择：webhook | pushplus | 企业微信
  mode: webhook

  # Webhook 模式配置
  webhook:
    enabled: true
    port: 8080
    secret_key: "your-secret-key-change-this"

    # 消息回调地址（由微信客户端或中间件提供）
    callback_url: "http://your-server-ip:8080/callback"

  # 通用配置
  llm:
    model: "gpt-4o-mini"
    temperature: 0.7
    max_tokens: 2048

  # 记忆系统
  memory:
    enabled: true
    sqlite_path: "/root/.hermes/profiles/default/memories.db"
    max_history: 50

  # 系统提示词
  system_prompt: |
    你是一个有帮助的 AI 助手，名为 Hermes。请用简洁、专业的中文回答用户的问题。
    如果用户的问题超出了你的知识范围，请诚实告知。

  # 安全设置
  security:
    # 允许访问的用户 ID 列表（留空表示全部允许）
    allowed_users: []
    # 每分钟最大消息数限制
    rate_limit: 20

3.3 启动微信插件

# 进入 Hermes Agent 根目录
cd /usr/local/lib/hermes-agent

# 以开发模式启动，观察日志
python -m hermes_agent.plugins.wechat --config plugins/wechat/config.yaml

启动成功后，你会看到类似输出：

[INFO] WeChat Plugin started on port 8080
[INFO] LLM connection established (model: gpt-4o-mini)
[INFO] Memory system initialized
[INFO] Listening for messages...

四、对接方案详解

Hermes Agent 提供了三种微信对接方式，你可以根据实际需求选择：

方案 A：Webhook 直连（最简单）

适用于个人使用或有固定 IP 的服务器：

# 使用 requests 向 Hermes Agent 发送消息
import requests

def send_wechat_message(text, user_id="default"):
    """通过 HTTP 接口发送消息"""
    payload = {
        "user_id": user_id,
        "message": text,
        "mode": "text"
    }

    response = requests.post(
        "http://localhost:8080/send",
        json=payload,
        headers={"X-Secret-Key": "your-secret-key"}
    )
    return response.json()

# 测试
result = send_wechat_message("你好，Hermes！")
print(result["reply"])

方案 B：PushPlus 推送（免服务器）

如果你没有公网 IP，可以使用 PushPlus 服务作为中转：

wechat:
  mode: pushplus

  pushplus:
    token: "your-pushplus-token"
    topic: group       # group(群组) / people(个人)
    template: markdown
    url: "http://your-blog.com/post/123"

注意：PushPlus 免费版每日有推送上限，企业版可解锁更高限额。详见 PushPlus 官方文档。

方案 C：企业微信机器人

适合团队内部使用，安全性更高：

wechat:
  mode: workwx

  workwx:
    corp_id: "your-corp-id"
    agent_id: "your-agent-id"
    secret: "your-app-secret"
    touser: "@all"       # 全员广播
    msgtype: "text"

五、测试与验证

5.1 本地测试

使用 curl 模拟微信消息：

curl -X POST http://localhost:8080/callback 
  -H "Content-Type: application/json" 
  -H "Authorization: Bearer your-secret-key" 
  -d '{
    "user_id": "test_user",
    "message": "请问今天天气如何？",
    "timestamp": 1717324800
  }'

预期响应：

{
  "status": "success",
  "reply": "我无法直接获取实时天气信息，建议您查询当地气象部门发布的最新天气预报。如果您需要我帮您设置一个定时天气提醒，请告诉我您的位置！",
  "tokens_used": 142,
  "response_time_ms": 1250
}

5.2 查看对话日志

所有对话都会记录在数据库中，可以通过以下方式查看：

# 查询最近 10 条对话记录
sqlite3 /root/.hermes/profiles/default/memories.db 
  "SELECT timestamp, user_id, content FROM conversations ORDER BY timestamp DESC LIMIT 10;"

# 查看某用户的完整历史
sqlite3 /root/.hermes/profiles/default/memories.db 
  "SELECT * FROM conversations WHERE user_id='test_user' ORDER BY timestamp ASC;"

5.3 性能监控

Hermes Agent 内置了 Prometheus 指标导出：

# 访问 /metrics 端点查看实时数据
curl http://localhost:8080/metrics

# 关键字段说明
# wechat_messages_total         — 累计处理消息数
# wechat_response_time_seconds  — 平均响应时间
# wechat_tokens_total           — 累计消耗 token 数

六、常见问题排查

遇到问题的朋友可以参考下表快速定位：

问题现象	可能原因	解决方案
连接被拒绝	端口未开放 / 防火墙拦截	`sudo ufw allow 8080/tcp`
LLM 返回空值	API Key 无效 / 网络不通	检查环境变量和网络连接
消息延迟高	模型响应慢 / Token 过长	降低 `max_tokens` 或使用更快的模型
内存溢出	历史记录过多	减少 `max_history` 参数值
认证失败	Secret Key 不匹配	确认配置文件中的密钥一致