别怕迁移!OpenClaw到Hermes一站式攻略

看完这篇微信QQ配置指南，我立刻删了旧系统

引言：为什么选择Hermes Agent？

如果你正在使用OpenClaw，那么你可能会对Nous Research推出的Hermes Agent感兴趣。作为新一代AI助手框架，Hermes Agent在保持OpenClaw强大功能的同时，提供了更现代的架构、更好的扩展性和更丰富的平台支持。

最近，Hermes Agent v0.9.0版本发布了一个全面的OpenClaw迁移工具，让用户可以无缝地将现有配置、记忆、技能和平台设置迁移到新系统。本文将为你提供从OpenClaw迁移到Hermes Agent的完整指南，特别聚焦于微信和QQ Bot的配置。

迁移的核心优势

向后兼容：支持从OpenClaw、Clawdbot和Moltbot迁移
数据保全：完整迁移SOUL.md、记忆文件、技能配置
平台支持：原生支持微信个人账号（iLink API）和QQ官方Bot API
双开方案：通过HermesClaw项目可同时运行两个系统

第一部分：Hermes Agent安装与基础迁移

1.1 安装Hermes Agent

首先，确保你的系统满足以下要求：

Python 3.10+
Git
基本的命令行操作知识

安装Hermes Agent：

# 克隆仓库
git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent

# 安装依赖
pip install -e .

1.2 迁移OpenClaw数据

Hermes提供了专门的迁移工具，支持多种迁移模式：

# 预览迁移内容（推荐先执行）
hermes claw migrate --dry-run

# 完整迁移（包含API密钥）
hermes claw migrate --preset full

# 仅迁移用户数据（不包含密钥）
hermes claw migrate --preset user-data

# 自定义源路径
hermes claw migrate --source /path/to/your/openclaw

1.3 迁移内容概览

迁移工具会自动处理以下内容：

类别	OpenClaw源	Hermes目标	说明
人格文件	workspace/SOUL.md	~/.hermes/SOUL.md	直接复制
长期记忆	workspace/MEMORY.md	~/.hermes/memories/MEMORY.md	解析为条目并去重
用户资料	workspace/USER.md	~/.hermes/memories/USER.md	同上
技能文件	workspace/skills/	~/.hermes/skills/openclaw-imports/	处理冲突选项
模型配置	models.providers.*	config.yaml → custom_providers	支持多种格式
API密钥	多种源	~/.hermes/.env	需--migrate-secrets参数

第二部分：微信个人账号配置指南

2.1 微信平台概述

Hermes Agent通过腾讯的iLink Bot API连接微信个人账号，支持以下功能：

文字消息收发
图片、语音、文件传输
群组消息处理
扫码登录

2.2 环境变量配置

在~/.hermes/.env文件中配置以下变量：

# 必需：iLink Token（从iLink控制台获取）
WEIXIN_TOKEN=your_i...here

# 必需：账户ID（登录后自动获取）
WEIXIN_ACCOUNT_ID=your_account_id

# 可选：基础URL（默认使用官方API）
WEIXIN_BASE_URL=https://ilinkai.weixin.qq.com

# 可选：CDN基础URL
WEIXIN_CDN_BASE_URL=https://novac2c.cdn.weixin.qq.com/c2c

# 权限控制：允许的用户（微信ID，多个用逗号分隔）
WEIXIN_ALLOWED_USERS=wxid_abc123,wxid_def456

# 权限控制：群组允许的用户
WEIXIN_GROUP_ALLOWED_USERS=wxid_abc123

# 消息策略：私聊策略（open | allowlist | disabled）
WEIXIN_DM_POLICY=allowlist

# 消息策略：群组策略（open | allowlist | disabled）
WEIXIN_GROUP_POLICY=allowlist

# 多行消息分割
WEIXIN_SPLIT_MULTILINE_MESSAGES=true

# Home Channel设置
WEIXIN_HOME_CHANNEL=your_home_chat_id
WEIXIN_HOME_CHANNEL_NAME=Home

2.3 扫码登录流程

首次配置微信需要扫码登录：

# 启动Hermes网关
hermes gateway start

# 查看网关日志，找到二维码
hermes gateway logs --tail 50

登录流程：

网关启动后会自动生成二维码
使用微信扫描二维码
在手机上确认登录
系统自动获取account_id并保存

2.4 配置文件方式

除了环境变量，还可以在config.yaml中配置：

platforms:
  weixin:
    enabled: true
    token: "your_ilink_token"
    extra:
      account_id: "your_account_id"
      dm_policy: "allowlist"
      group_policy: "allowlist"
      allow_from: ["wxid_abc123", "wxid_def456"]
      group_allow_from: ["wxid_abc123"]
      split_multiline_messages: true

2.5 常见问题

Q1: 二维码不显示或过期？

检查WEIXIN_TOKEN是否正确
确保网络可以访问ilinkai.weixin.qq.com
重新启动网关：hermes gateway restart

Q2: 消息发送失败？

检查account_id是否正确
确认消息长度不超过微信限制
查看网关日志：hermes gateway logs --tail 100

Q3: 图片/文件发送失败？

检查文件大小（微信限制20MB）
确认CDN配置正确
查看媒体处理日志

第三部分：QQ Bot配置指南

3.1 QQ Bot平台概述

Hermes Agent通过QQ官方Bot API v2连接，支持：

文字消息（支持Markdown格式）
图片、语音、文件
群组和私聊消息
语音转文字（支持腾讯ASR和第三方服务）

3.2 环境变量配置

在~/.hermes/.env文件中配置：

# 必需：QQ Bot App ID
QQ_APP_ID=your_app_id

# 必需：QQ Bot Client Secret
QQ_CLIENT_SECRET=your_c...cret

# 可选：允许的用户（OpenID列表，逗号分隔）
QQ_ALLOWED_USERS=openid_1,openid_2

# 可选：群组允许的用户
QQ_GROUP_ALLOWED_USERS=group_openid_1

# 可选：Home Channel设置
QQ_HOME_CHANNEL=your_home_channel_id
QQ_HOME_CHANNEL_NAME=Home

# 可选：STT语音识别配置
QQ_STT_API_KEY=***
QQ_STT_PROVIDER=zai  # zai, openai等
QQ_STT_BASE_URL=https://open.bigmodel.cn/api/coding/paas/v4
QQ_STT_MODEL=glm-asr

3.3 配置文件方式

config.yaml配置示例：

platforms:
  qqbot:
    enabled: true
    extra:
      app_id: "your_app_id"
      client_secret: "your_client_secret"
      markdown_support: true  # 启用Markdown支持
      dm_policy: "allowlist"  # open | allowlist | disabled
      allow_from: ["openid_1"]
      group_policy: "allowlist"
      group_allow_from: ["group_openid_1"]
      stt:
        provider: "zai"
        baseUrl: "https://open.bigmodel.cn/api/coding/paas/v4"
        apiKey: "your_stt_api_key"
        model: "glm-asr"

3.4 语音转文字优先级

QQ Bot的语音消息转文字按以下优先级处理：

腾讯内置ASR：免费，优先尝试
配置的STT服务：当内置ASR失败时使用
跳过转文字：两者都失败时保留语音文件

3.5 常见问题

Q1: WebSocket连接失败？

检查app_id和client_secret是否正确
确认QQ Bot已开通并配置了WebSocket网关
查看网络连接：curl https://api.sgroup.qq.com

Q2: 消息格式不支持？

启用markdown_support: true
检查消息类型设置
确认Bot权限足够

Q3: 媒体文件上传失败？

检查文件大小限制（QQ Bot有特定限制）
确认API调用频率未超限
查看详细的错误日志

第四部分：踩坑经验与解决方案

4.1 迁移过程中的常见问题

问题1：API密钥迁移不全

症状：迁移后某些服务无法使用
原因：OpenClaw密钥存储位置多样
解决：

# 检查所有可能的密钥源
hermes claw migrate --dry-run --preset full

# 手动添加缺失密钥
hermes config set custom_providers.openai.api_key "sk-..."

问题2：技能冲突

症状：迁移后某些技能不生效
原因：技能文件重名冲突
解决：

# 使用重命名策略迁移技能
hermes claw migrate --skill-conflict rename

# 手动检查技能目录
ls -la ~/.hermes/skills/openclaw-imports/

问题3：微信account_id丢失

症状：微信重新登录后需要重新配置
原因：account_id未正确保存
解决：

# 检查微信账户存储
ls -la ~/.hermes/weixin/accounts/

# 重新登录获取account_id
rm -rf ~/.hermes/weixin/accounts/*
hermes gateway restart

4.2 平台配置最佳实践

权限控制：始终使用allowlist模式，避免未授权访问
日志记录：开启详细日志，便于调试

hermes config set logging.level DEBUG

定期备份：迁移后备份关键配置

cp -r ~/.hermes ~/.hermes.backup.$(date +%Y%m%d)

分段测试：先测试文字消息，再测试媒体功能

第五部分：双开方案 - HermesClaw项目

5.1 什么是HermesClaw？

HermesClaw是一个社区项目，允许你在同一个微信账号上同时运行Hermes Agent和OpenClaw。这对于想要平滑过渡的用户特别有用。

项目地址：https://github.com/AaronWong1999/hermesclaw

5.2 工作原理

HermesClaw作为中间层，实现：

消息路由：将微信消息分发到Hermes或OpenClaw
状态同步：保持两个系统的会话状态
冲突处理：处理两个系统同时响应的冲突

5.3 部署步骤

# 克隆HermesClaw
git clone https://github.com/AaronWong1999/hermesclaw.git
cd hermesclaw

# 安装依赖
pip install -r requirements.txt

# 配置桥接
cp config.example.yaml config.yaml
# 编辑config.yaml，配置Hermes和OpenClaw的连接信息

# 启动桥接服务
python hermesclaw_bridge.py

5.4 配置示例

# config.yaml
hermes:
  gateway_url: "http://localhost:8080"
  auth_token: "your_hermes_token"

openclaw:
  api_url: "http://localhost:3000"
  api_key: "your_openclaw_key"

wechat:
  ilink_token: "your_ilink_token"
  # 其他微信配置...

routing:
  default: "hermes"  # 默认路由到Hermes
  rules:
    - pattern: "/help"
      target: "openclaw"
    - pattern: "/legacy"
      target: "openclaw"

5.5 双开方案的优势

无缝过渡：用户无需立即放弃OpenClaw
功能对比：可以同时测试两个系统的表现
故障转移：一个系统故障时，另一个可继续服务
数据同步：逐步将数据迁移到Hermes

第六部分：迁移后验证与优化

6.1 验证清单

迁移完成后，执行以下验证：

# 1. 检查系统状态
hermes status

# 2. 验证API密钥
hermes config get custom_providers

# 3. 测试基础功能
hermes chat "Hello, test migration"

# 4. 检查技能加载
hermes skills list

# 5. 测试平台连接
hermes gateway status

6.2 性能优化建议

会话管理：

# config.yaml优化
session_reset:
  mode: ["daily", "idle"]
  idle_minutes: 60
  at_hour: 3  # 凌晨3点重置

内存管理：

# 清理旧会话
hermes sessions cleanup --days 7

# 优化记忆存储
hermes memory optimize

网关调优：

gateway:
  worker_processes: 2  # 根据CPU核心数调整
  max_connections: 100

6.3 监控与维护

设置监控告警：

# 健康检查脚本
#!/bin/bash
if ! curl -f http://localhost:8080/health > /dev/null 2>&1; then
    systemctl --user restart hermes-gateway
    echo "Hermes gateway restarted at $(date)" >> /tmp/hermes-monitor.log
fi

定期维护任务：

# 添加到crontab
0 2 * * * /usr/bin/hermes sessions cleanup --days 7
0 3 * * * /usr/bin/hermes memory optimize

总结与建议

迁移策略选择

根据你的使用场景，可以选择不同的迁移策略：

激进迁移：直接完全迁移，适合新项目或测试环境
渐进迁移：使用双开方案，逐步过渡
并行运行：重要生产环境保持双系统运行

微信/QQ平台特别提示

微信：
- iLink API有频率限制，注意控制消息频率
- 群组消息需要额外权限配置
- 媒体文件注意大小限制
QQ Bot：
- 官方API限制较多，仔细阅读文档
- WebSocket连接需要保持活跃
- Markdown格式能显著提升体验

后续支持

官方文档：https://hermesagent.dev
GitHub Issues：报告问题和功能请求
社区讨论：加入Discord或微信群获取帮助

最后的建议

迁移过程可能会遇到挑战，但Hermes Agent提供的现代架构和持续更新值得投入。建议：

充分测试：在非生产环境充分测试所有功能
备份数据：迁移前后都要备份关键数据
逐步切换：先从非关键功能开始迁移
参与社区：分享你的经验，帮助他人

通过本文的指南，你应该能够顺利完成从OpenClaw到Hermes Agent的迁移，并在微信和QQ平台上获得更好的体验。祝你迁移顺利！

本文基于Hermes Agent v0.8.0和OpenClaw迁移工具编写，具体细节可能随版本更新而变化。建议查阅官方文档获取最新信息。