Hermes Agent 从 OpenClaw 迁移指南：无缝切换到 Hermes

Hermes Agent 提供了从 OpenClaw（及早期 Clawdbot/Moltbot）一键迁移的能力。本文详细说明迁移涵盖的内容、配置项映射关系，以及迁移后需要检查的事项，帮助你无缝切换到 Hermes。

快速开始

# 先预览再迁移（始终先展示预览，确认后执行）
hermes claw migrate

# 仅预览，不做任何更改
hermes claw migrate --dry-run

# 完整迁移（含 API key），跳过确认
hermes claw migrate --preset full --migrate-secrets --yes

迁移始终会在执行任何更改前展示完整的导入预览列表，确认后再继续。

默认从 ~/.openclaw/ 读取。旧版 ~/.clawdbot/ 或 ~/.moltbot/ 目录会自动检测，旧版配置文件名（clawdbot.json、moltbot.json）同样自动识别。

选项说明

迁移内容详情

人设、记忆与指令

工作区文件同时会在 workspace.default/ 和 workspace-main/ 路径下检查（OpenClaw 在近期版本中将 workspace/ 重命名为 workspace-main/，多 Agent 设置使用 workspace-{agentId}）。

Skills（4 个来源）

Skill 冲突通过 --skill-conflict 处理：skip 保留已有 Hermes skill，overwrite 替换，rename 创建 -imported 副本。

模型与 Provider 配置

Agent 行为

Session 重置策略

注意：OpenClaw 还有 session.resetTriggers（简单字符串数组，如 ["daily", "idle"]）。如果结构化的 session.reset 不存在，迁移会从 resetTriggers 推断。

MCP Server

TTS（文本转语音）

TTS 设置从 OpenClaw 的 两个 配置位置读取，优先级如下：

1. messages.tts.providers.{provider}.*（规范位置）
2. 顶层 talk.providers.{provider}.*（回退）
3. 旧版扁平键 messages.tts.{provider}.*（最旧格式）

消息平台

其他配置

已归档（Hermes 无直接对应项）

以下内容保存到 ~/.hermes/migration/openclaw/<timestamp>/archive/ 供手动审查：

API Key 解析

启用 --migrate-secrets 时，API Key 按以下 四个来源 的优先级收集：

1. 配置值 — openclaw.json 中的 models.providers.*.apiKey 及 TTS provider 密钥
2. 环境文件 — ~/.openclaw/.env（如 OPENROUTER_API_KEY、ANTHROPIC_API_KEY 等）
3. 配置内 env 子对象 — openclaw.json → "env" 或 "env"."vars"（部分安装将密钥存储于此而非独立的 .env 文件）
4. Auth profiles — ~/.openclaw/agents/main/agent/auth-profiles.json（每个 Agent 的凭证）

配置值优先级最高，后续来源依次填充剩余空缺。

支持的 Key 目标

OPENROUTER_API_KEY、OPENAI_API_KEY、ANTHROPIC_API_KEY、DEEPSEEK_API_KEY、GEMINI_API_KEY、ZAI_API_KEY、MINIMAX_API_KEY、ELEVENLABS_API_KEY、TELEGRAM_BOT_TOKEN、VOICE_TOOLS_OPENAI_KEY

不在白名单中的 Key 不会被复制。

SecretRef 处理

OpenClaw 中 Token 和 API Key 的配置值可以是三种格式：

// 纯字符串
"channels": { "telegram": { "botToken": "123456:ABC-DEF..." } }

// 环境变量模板
"channels": { "telegram": { "botToken": "${TELEGRAM_BOT_TOKEN}" } }

// SecretRef 对象
"channels": { "telegram": { "botToken": { "source": "env", "id": "TELEGRAM_BOT_TOKEN" } } }

迁移会解析所有三种格式。对于环境变量模板和 source: "env" 的 SecretRef 对象，会从 ~/.openclaw/.env 和 openclaw.json 的 env 子对象中查找值。source: "file" 或 source: "exec" 的 SecretRef 对象无法自动解析 — 迁移会发出警告，这些值需通过 hermes config set 手动添加。

迁移后检查

1. 查看迁移报告 — 完成后会打印迁移、跳过和冲突的条目计数。

2. 审查归档文件 — ~/.hermes/migration/openclaw/<timestamp>/archive/ 中的内容需要手动处理。

3. 启动新 Session — 导入的 Skills 和记忆条目在新 Session 中生效，当前 Session 不会自动加载。

4. 验证 API Key — 运行 hermes status 检查 Provider 认证状态。

5. 测试消息平台 — 如果迁移了平台 Token，重启 gateway：systemctl --user restart hermes-gateway

6. 检查 Session 策略 — 确认 hermes config get session_reset 符合预期。

7. 重新配对 WhatsApp — WhatsApp 使用 QR 码配对（Baileys），不支持 Token 迁移。运行 hermes whatsapp 进行配对。

8. 归档清理 — 确认一切正常后，运行 hermes claw cleanup 将残留的 OpenClaw 目录重命名为 .pre-migration/（防止状态混淆）。

常见问题

"OpenClaw directory not found"

迁移依次检查 ~/.openclaw/、~/.clawdbot/、~/.moltbot/。如果你的安装在其他位置，使用 --source /path/to/your/openclaw。

"No provider API keys found"

Key 可能存储在多个位置，取决于 OpenClaw 版本：openclaw.json 中 models.providers.*.apiKey 内联值、~/.openclaw/.env、openclaw.json 的 "env" 子对象、或 agents/main/agent/auth-profiles.json。迁移会检查全部四个来源。如果 Key 使用 source: "file" 或 source: "exec" 的 SecretRef，无法自动解析 — 通过 hermes config set 手动添加。

迁移后 Skills 未出现

导入的 Skills 位于 ~/.hermes/skills/openclaw-imports/。需要启动新 Session 才能生效，或运行 /skills 确认是否已加载。

TTS 声音未迁移

OpenClaw 将 TTS 设置存储在两个位置：messages.tts.providers.* 和顶层 talk 配置。迁移会检查两者。如果你的声音 ID 是通过 OpenClaw UI 设置的（存储在不同路径），可能需要手动设置：hermes config set tts.elevenlabs.voice_id YOUR_VOICE_ID。