Hermes Agent

主题

从 OpenClaw 迁移 ​

如果你之前使用 OpenClaw 作为 AI 智能体框架，可以使用内置的迁移工具将数据平滑迁移到 Hermes Agent，整个过程只需几分钟。

迁移概览 ​

hermes claw migrate 命令会自动读取 OpenClaw 的配置目录，将兼容的数据转换并写入 Hermes Agent 的对应位置。

可迁移的数据类型：

数据类型OpenClaw 位置Hermes Agent 位置
人格定义~/.openclaw/personas/~/.hermes/personas/
记忆条目~/.openclaw/memory/~/.hermes/memory/
自定义技能~/.openclaw/skills/~/.hermes/skills/
消息平台配置~/.openclaw/messaging.yaml~/.hermes/config.yaml (gateway 部分)
API 凭据~/.openclaw/.env~/.hermes/.env

迁移前准备 ​

1. 确保 Hermes Agent 已正确安装 ​

bash
hermes doctor

所有检查项应显示 ✓。

2. 备份 OpenClaw 数据 ​

虽然迁移工具不会修改 OpenClaw 的原始数据，但建议在迁移前手动备份：

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

3. 确认 OpenClaw 数据目录位置 ​

默认数据目录为 ~/.openclaw。如果你使用了自定义路径，需要在命令中通过 --source 参数指定。

迁移命令 ​

基础用法 ​

bash
hermes claw migrate

不带任何参数时，迁移工具会：

  1. 自动检测 ~/.openclaw 目录
  2. 扫描所有可迁移的数据
  3. 在执行前显示迁移计划并请求确认
  4. 执行迁移并输出详细报告

完整命令格式 ​

bash
hermes claw migrate [OPTIONS]

命令选项详解 ​

--dry-run：预演模式 ​

在不实际写入任何文件的情况下，预览完整的迁移计划：

bash
hermes claw migrate --dry-run

输出示例：

=== 迁移预演报告（--dry-run，不会实际执行） ===

源目录：~/.openclaw
目标目录：~/.hermes

待迁移项目：
  ✓ 人格定义 (3 个)
      - assistant.yaml → personas/assistant.yaml
      - coder.yaml     → personas/coder.yaml
      - writer.yaml    → personas/writer.yaml

  ✓ 记忆条目 (147 条)
      - memory.db → memory/memory.db（格式转换：SQLite v1 → v2）

  ✓ 自定义技能 (12 个)
      - git_helper.yaml      → skills/git_helper.yaml
      - daily_report.yaml    → skills/daily_report.yaml
      - ... 等 10 个

  ✓ 消息平台配置
      - Telegram Bot Token   → config.yaml (gateway.telegram)
      - Discord Bot Token    → config.yaml (gateway.discord)

  ✓ API 凭据 (5 个 Key)
      - OPENAI_API_KEY       → .env
      - ANTHROPIC_API_KEY    → .env
      - ... 等 3 个

冲突检测：
  ⚠ skills/git_helper.yaml 已存在于目标目录（使用 --overwrite 覆盖）

预计操作：写入 23 个文件，转换 1 个数据库，合并 1 个配置文件

运行不带 --dry-run 的命令以执行迁移。

建议：正式迁移前始终先运行 --dry-run 确认无误。

--preset：预设迁移范围 ​

使用预定义的迁移范围，只迁移特定类型的数据：

bash
# 只迁移用户数据（人格、记忆、技能）
hermes claw migrate --preset user-data

# 只迁移配置（消息平台、API 凭据）
hermes claw migrate --preset config-only

# 只迁移记忆数据库
hermes claw migrate --preset memory-only

# 只迁移技能文件
hermes claw migrate --preset skills-only

# 迁移所有数据（默认）
hermes claw migrate --preset all
预设名称包含内容
user-data人格定义、记忆条目、自定义技能
config-only消息平台配置、API 凭据
memory-only仅记忆数据库
skills-only仅技能文件
all所有可迁移数据（默认）

--overwrite：覆盖已有文件 ​

当目标位置已存在同名文件时，默认情况下迁移工具会跳过这些文件并发出警告。使用 --overwrite 强制覆盖：

bash
hermes claw migrate --overwrite

注意：--overwrite 会无提示地覆盖目标文件。如果你已在 Hermes Agent 中自定义了同名技能或人格，这些修改将被丢失。建议先用 --dry-run 确认冲突范围。

--source：指定源目录 ​

如果 OpenClaw 数据不在默认位置：

bash
hermes claw migrate --source /custom/path/to/openclaw

--target：指定目标目录 ​

如果 Hermes Agent 数据不在默认位置：

bash
hermes claw migrate --target /custom/path/to/hermes

组合使用 ​

bash
# 预演：只迁移用户数据，覆盖冲突文件
hermes claw migrate --dry-run --preset user-data --overwrite

# 正式执行
hermes claw migrate --preset user-data --overwrite

分步迁移指南 ​

以下是推荐的迁移步骤，适合希望精细控制迁移过程的用户。

第 1 步：运行预演，了解迁移范围 ​

bash
hermes claw migrate --dry-run

仔细阅读输出，注意：

  • 冲突文件列表
  • 格式转换说明
  • 预计写入的文件数量

第 2 步：迁移 API 凭据 ​

凭据是最重要的，先迁移确保 Hermes Agent 能正常连接模型：

bash
hermes claw migrate --preset config-only

验证 API Key 是否生效：

bash
hermes doctor
hermes chat -q "你好"

第 3 步：迁移记忆数据库 ​

bash
hermes claw migrate --preset memory-only

验证记忆是否正确导入：

bash
hermes memory list

第 4 步：迁移技能文件 ​

bash
hermes claw migrate --preset skills-only

验证技能是否可用：

bash
hermes skills list

逐一测试关键技能确保功能正常：

bash
hermes -s your_skill_name

第 5 步：迁移人格定义 ​

bash
hermes claw migrate --preset user-data
# （此时记忆和技能已迁移，--preset user-data 只会新增人格定义）

验证人格：

bash
hermes --persona your_persona_name

第 6 步：配置消息平台网关 ​

消息平台 Token 会自动迁移，但需要手动重启网关使配置生效：

bash
hermes gateway restart

在各平台测试机器人是否正常响应。

第 7 步：清理与验证 ​

全量验证：

bash
hermes doctor
hermes config show
hermes skills list
hermes memory list

确认一切正常后，可以选择保留或删除 OpenClaw 安装：

bash
# 保留备份，暂时不删除（推荐）
# 等使用 Hermes Agent 一段时间确认无误后再删除

# 删除 OpenClaw（确认无误后执行）
# rm -rf ~/.openclaw

迁移数据格式说明 ​

人格定义转换 ​

OpenClaw 人格格式（.claw 文件）会自动转换为 Hermes Agent 的 YAML 格式：

OpenClaw 格式（persona.claw）：

[persona]
name = MyAssistant
prompt = You are a helpful assistant...
language = zh

转换后（persona.yaml）：

yaml
id: MyAssistant
name: MyAssistant
description: 从 OpenClaw 迁移
system_prompt: |
  You are a helpful assistant...
language: zh

记忆数据库转换 ​

OpenClaw 使用 SQLite v1 格式存储记忆，Hermes Agent 使用 v2 格式（新增向量索引支持）。迁移工具会自动完成格式转换，所有记忆条目内容保持不变。

技能文件转换 ​

OpenClaw 技能文件（.skill TOML 格式）会转换为 Hermes Agent 的 YAML 格式：

OpenClaw 格式（skill.skill）：

toml
[skill]
name = "git_summary"
description = "Generate git summary"

[[steps]]
type = "shell"
cmd = "git log --oneline -10"

转换后（git_summary.yaml）：

yaml
name: git_summary
description: Generate git summary
version: "1.0"
migrated_from: openclaw

steps:
  - tool: terminal
    command: git log --oneline -10

消息平台配置转换 ​

OpenClaw 的 messaging.yaml 中的 Bot Token 和配置会被提取并合并到 Hermes Agent 的 config.yaml 中的 gateway 部分。

常见迁移问题 ​

迁移后技能运行报错 ​

OpenClaw 技能中可能使用了 OpenClaw 特有的内置命令（如 !claw_search），这些命令在 Hermes Agent 中不存在。需要手动将其替换为对应的 Hermes Agent 工具调用。

查找需要手动处理的技能：

bash
hermes claw migrate --dry-run 2>&1 | grep "需要手动处理"

API Key 迁移后无效 ​

部分 OpenClaw 版本对 API Key 进行了加密存储。如果自动迁移的 Key 无效，请手动复制原始密钥：

bash
# 查看 OpenClaw 原始配置
cat ~/.openclaw/.env

# 手动写入 Hermes Agent
hermes config set OPENAI_API_KEY your_actual_key

记忆条目过多导致迁移缓慢 ​

如果你的 OpenClaw 记忆数据库非常大（数千条以上），格式转换可能需要几分钟。这是正常现象，请耐心等待。

如需加速，可以先迁移最近的记忆：

bash
hermes claw migrate --preset memory-only --since 2024-01-01

消息平台 Webhook 地址变更 ​

Hermes Agent 的 Webhook 地址格式与 OpenClaw 不同，迁移后需要在各平台的开发者控制台更新 Webhook URL：

旧地址（OpenClaw）：https://your-server.com/openclaw/webhook
新地址（Hermes）：  https://your-server.com/hermes/gateway/webhook

获取帮助 ​

如果在迁移过程中遇到问题：

bash
# 查看迁移命令完整帮助
hermes claw migrate --help

# 生成迁移诊断报告
hermes claw migrate --dry-run --verbose > migration_report.txt

也可以在 GitHub Issues 中提交问题，并附上 migration_report.txt 的内容（注意先手动删除其中的密钥信息）。

基于 MIT 许可发布 | 由 Nous Research 开发

非官方中文文档 · 由 XAAPI 社区翻译维护