Hermes Agent 微信对接部署指南

发布于 6 天前  16 次阅读

Hermes Agent 微信对接部署指南

从 OpenClaw 迁移到 Hermes Agent，实现微信消息收发

目录

背景介绍

为什么选择 Hermes Agent？

Hermes Agent 是 Nous Research 开发的自改进 AI Agent，具有以下特点：

  • 闭环学习 - 从经验中创建技能，使用中改进技能
  • 多平台支持 - Telegram、Discord、Slack、WhatsApp、Signal、微信等
  • 多模型支持 - OpenRouter、OpenAI、Anthropic、NVIDIA NIM、MiniMax、Kimi 等，以及自定义 OpenAI 兼容 API
  • 轻量运行 - 可在 $5 VPS 或无服务器基础设施上运行

环境要求

系统要求

  • Linux (Ubuntu/Debian 推荐)
  • Python 3.11+
  • systemd (服务管理)

检查环境

# 检查 Python 版本
python3 --version  # 需要 3.11+

# 检查 systemd
systemctl --version

安装步骤

1. 安装 Hermes Agent

方式一：官方安装脚本

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
source ~/.bashrc

方式二：从源码安装

git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent
./setup-hermes.sh
source ~/.bashrc

2. 验证安装

hermes --version
# 输出: Hermes Agent v0.12.0 (2026.4.30)

模型配置

使用自定义 OpenAI 兼容 API

Hermes 支持通过 custom_providers 配置使用任何 OpenAI 兼容的 API。

配置步骤：

# 设置模型提供商为自定义 provider 名称
hermes config set model.provider your-provider-name

# 设置模型名称（不带 provider 前缀）
hermes config set model.default your-model-id

# 配置 custom_providers
hermes config set custom_providers.0.name your-provider-name
hermes config set custom_providers.0.base_url https://your-api-endpoint/v1
hermes config set custom_providers.0.api_key your-api-key
hermes config set custom_providers.0.api_mode chat_completions
hermes config set custom_providers.0.model your-model-id

示例：使用讯飞 CodingPlan API

hermes config set model.provider astroncodingplan
hermes config set model.default astron-code-latest

hermes config set custom_providers.0.name astroncodingplan
hermes config set custom_providers.0.base_url https://maas-coding-api.cn-huabei-1.xf-yun.com/v2
hermes config set custom_providers.0.api_key your-api-key
hermes config set custom_providers.0.api_mode chat_completions
hermes config set custom_providers.0.model astron-code-latest

重要提示：

  • model.default 应只包含模型 ID，不带 provider 前缀（如 astron-code-latest，而非 astroncodingplan/astron-code-latest）
  • custom_providers.0.model 也应只包含模型 ID
  • API Key 格式根据服务商要求配置

验证模型配置

hermes status

检查输出中的 Model 和 Provider 是否正确。

微信对接

Hermes 通过 iLink Bot API 连接微信个人账号，使用扫码登录方式。

1. 安装微信依赖

pip install aiohttp cryptography

2. 扫码登录微信

运行设置向导，选择微信平台：

hermes gateway setup

向导会：

  1. 请求二维码
  2. 在终端显示二维码（或提供 URL）
  3. 等待你用微信扫码
  4. 在手机上确认登录
  5. 自动保存账号凭据

看到以下提示表示成功：

微信连接成功，account_id=xxx@im.bot

3. 配置账号 ID

扫码登录后，账号信息会自动保存。如果需要手动配置：

# 在 ~/.hermes/.env 中添加
WEIXIN_ACCOUNT_ID=your-account-id
WEIXIN_DM_POLICY=open

4. 启动 Gateway

hermes gateway start

5. 验证连接

hermes gateway status

输出应显示：

✓ weixin connected
Gateway running with 1 platform(s)

6. 测试消息收发

在微信中给 iLink Bot 发送消息，Hermes 会自动回复。

查看日志确认：

tail -f ~/.hermes/logs/gateway.log

正常日志示例：

[Weixin] inbound from=xxx type=dm media=0
inbound message: platform=weixin ... msg='你好'
response ready: platform=weixin ... response=52 chars
[Weixin] Sending response (52 chars) to xxx

OpenClaw 迁移

Hermes 内置 OpenClaw 迁移工具，可导入配置和数据。

迁移预览

hermes claw migrate --dry-run

执行迁移

# 交互式迁移
hermes claw migrate

# 非交互式
hermes claw migrate --preset full --overwrite --yes

可迁移内容：

项目 说明
SOUL.md 人格配置文件
MEMORY.md 长期记忆
USER.md 用户配置
model-config 模型配置
skills 用户创建的技能

服务管理

安装 Gateway 服务

hermes gateway install

启用自启动

# 启用 linger（用户未登录时服务也能运行）
loginctl enable-linger $USER

# 启用服务自启动
systemctl --user enable hermes-gateway

服务操作命令

# 启动
hermes gateway start

# 停止
hermes gateway stop

# 重启
hermes gateway restart

# 查看状态
hermes gateway status

# 查看日志
journalctl --user -u hermes-gateway -f

配置持久化运行

确保以下配置：

  • Linger=yes - 用户未登录时服务也能运行
  • enabled - 服务自启动
  • Restart=always - 服务崩溃后自动重启
# 检查 linger
loginctl show-user $USER | grep Linger

# 检查服务自启动
systemctl --user is-enabled hermes-gateway

常见问题

Q: 模型返回 "Model Not Found" 错误

原因： 模型名称配置错误

解决：
确保 model.default 和 custom_providers.0.model 只包含模型 ID，不带 provider 前缀。

# 正确
hermes config set model.default astron-code-latest

# 错误
hermes config set model.default astroncodingplan/astron-code-latest

Q: Gateway 启动失败，提示 "Unknown provider"

原因： provider 名称未在 custom_providers 中定义

解决：
确保 model.provider 与 custom_providers.0.name 一致。

Q: 微信扫码登录失败

排查步骤：

  1. 检查网络连接
  2. 确认已安装 aiohttp 和 cryptography
  3. 检查二维码是否过期（会自动刷新最多 3 次）

Q: Gateway 收到消息但不回复

排查步骤：

  1. 检查模型配置是否正确：hermes status
  2. 查看错误日志：tail ~/.hermes/logs/errors.log
  3. 测试 API 是否正常工作

Q: 重启后服务没有自动启动

解决：

loginctl enable-linger $USER
systemctl --user enable hermes-gateway

Q: 如何切换到 OpenClaw

Hermes 和 OpenClaw 不能同时使用同一个微信账号。切换步骤：

# 停止 Hermes
hermes gateway stop

# 启动 OpenClaw
systemctl --user start openclaw-gateway

附录

项目链接

项目 GitHub 官网
Hermes Agent NousResearch/hermes-agent hermes-agent.nousresearch.com
OpenClaw openclaw/openclaw openclaw.ai

配置文件路径

文件 路径
Hermes 配置 ~/.hermes/config.yaml
Hermes 环境变量 ~/.hermes/.env
Hermes 记忆 ~/.hermes/memories/
Hermes 人格 ~/.hermes/SOUL.md
Hermes 微信账号 ~/.hermes/weixin/accounts/
Gateway 日志 ~/.hermes/logs/gateway.log
错误日志 ~/.hermes/logs/errors.log

微信配置环境变量

变量 说明
WEIXIN_ACCOUNT_ID iLink Bot 账号 ID（扫码登录后自动保存）
WEIXIN_TOKEN iLink Bot Token（自动保存）
WEIXIN_BASE_URL iLink API 地址（默认官方地址）
WEIXIN_DM_POLICY 私聊策略：open、allowlist、disabled
WEIXIN_ALLOWED_USERS 允许的用户 ID 列表

文档更新时间：2026-05-03

新一技术 – 个人博客
最后更新于 2026-05-02
啥也没有呀