从 OpenClaw 迁移至 Hermes：完整指南与深度解读

背景

在 AI 代理（AI Agent）生态系统中，工具链的迭代速度极快。OpenClaw（及其前身 Clawdbot/Moldbot）曾是许多开发者本地运行 AI 代理的首选框架。然而，随着 Hermes 平台的崛起，用户面临着从旧有架构向新架构迁移的需求。

Hermes 提供了一个名为 hermes claw migrate 的工具，旨在自动化这一过程。该工具不仅负责数据的搬运，更致力于解决多提供商配置复杂、API 密钥管理混乱以及技能（Skills）冲突等痛点。特别是对于使用多提供商（Multi-provider）配置的用户，Hermes 通过其 Portal 服务，将原本分散的 OAuth 认证整合为单一登录入口，支持 300 多个模型及 Tool Gateway，极大地简化了用户体验。

本文基于 Hacker News 上的技术文档，详细解读如何从 OpenClaw 平滑迁移至 Hermes，涵盖配置映射、密钥处理、潜在冲突及后续验证步骤。

核心内容

1. 迁移流程与操作选项

迁移过程设计为“预览优先”，确保用户在执行任何更改前都能清楚了解影响范围。

• 标准迁移：

  hermes claw migrate
  

  系统会先展示完整预览列表，随后询问用户是否确认。

• 仅预览（Dry Run）：

  hermes claw migrate --dry-run
  

  仅显示将导入的内容，不修改任何文件。

• 全自动迁移：

  hermes claw migrate --preset full --migrate-secrets --yes
  

  包含 API 密钥迁移，跳过确认步骤，适用于熟悉风险的高级用户。

数据源检测： 工具默认读取 ~/.openclaw/ 目录。若未找到，会自动检测旧版目录 ~/.clawdbot/ 或 ~/.moltbot/，并兼容旧版配置文件名（如 clawdbot.json, moltbot.json）。

2. 迁移范围与配置映射

迁移工具并非简单复制文件，而是进行语义级的配置转换。

• 基础设置：

  • 迁移 Persona（人格）、Memory（记忆）和 Instructions（指令）。
  • 工作区文件：优先读取 workspace.default/，若不存在则回退至 workspace-main/。注意：OpenClaw 近期版本已将 workspace/ 重命名为 workspace-main/，且多代理设置使用 workspace-{agentId}。

• Skills（技能）处理：

  • 支持从 4 个来源导入技能。
  • 冲突解决策略（通过 --skill-conflict 参数控制）：
    • skip：保留现有 Hermes 技能，跳过导入。
    • overwrite：直接覆盖现有技能。
    • rename：创建带有 -imported 后缀的副本。

• 模型与提供商配置：

  • 迁移 Agent 行为、会话重置策略（Session reset policies）。
  • 会话重置逻辑兼容：OpenClaw 使用 session.resetTriggers（字符串数组，如 ["daily", "idle"]）。若 Hermes 配置中缺少结构化的 session.reset，迁移工具会自动从 resetTriggers 推断并转换。

• 其他组件：

  • MCP 服务器配置。
  • TTS（文本转语音）设置。
  • 消息平台配置。

3. API 密钥与敏感信息处理

这是迁移中最关键且易出错的部分。启用 --migrate-secrets 后，工具按以下优先级顺序收集 API 密钥：

1. 配置文件值：openclaw.json 中的 models.providers.*.apiKey 及 TTS 提供商密钥。
2. 环境变量文件：~/.openclaw/.env（如 OPENROUTER_API_KEY, ANTHROPIC_API_KEY 等）。
3. 配置内的 Env 子对象：openclaw.json 中的 "env" 或 "env"."vars" 字段。
4. Auth Profiles：~/.openclaw/agents/main/agent/auth-profiles.json 中的每代理凭据。

支持的目标密钥列表： 仅限以下密钥会被迁移，不在白名单中的密钥将被忽略： 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。

SecretRef 处理机制： OpenClaw 支持三种密钥格式，迁移工具的处理方式如下：

• 纯字符串：直接迁移。
• 环境变量模板（如 ${TELEGRAM_BOT_TOKEN}）：工具会在 ~/.openclaw/.env 和 openclaw.json 的 env 子对象中查找实际值并迁移。
• SecretRef 对象：
  • 若 source: "env"：自动解析并迁移。
  • 若 source: "file" 或 source: "exec"：无法自动解析。迁移工具会发出警告，用户需手动通过 hermes config set 在 Hermes 中重新配置这些值。

4. TTS 配置的特殊性

TTS 设置读取具有明确的优先级顺序：

1. messages.tts.providers.{provider}.*（标准位置）
2. talk.providers.{provider}.*（回退位置）
3. messages.tts.{provider}.*（最旧格式）

若 TTS 语音 ID 是通过 OpenClaw UI 设置的（存储在非标准路径），迁移可能失败，需手动执行： hermes config set tts.elevenlabs.voice_id YOUR_VOICE_ID

5. 迁移后验证与清理

迁移完成后，必须执行以下验证步骤：

1. 检查迁移报告：查看成功、跳过及冲突项的数量。
2. 审查归档文件：检查 ~/.hermes/migration/openclaw/<timestamp>/archive/，处理需要手动注意的项目。
3. 启动新会话：导入的技能和记忆仅在新会话中生效，当前会话不会立即更新。
4. 验证 API 密钥：运行 hermes status 检查提供商认证状态。
5. 测试消息功能：若迁移了平台 Token，需重启网关：systemctl --user restart hermes-gateway。
6. 检查会话策略：运行 hermes config show 确认 session_reset 值符合预期。
7. WhatsApp 重新配对：WhatsApp 使用 QR 码配对（Baileys 库），不支持 Token 迁移。需运行 hermes whatsapp 重新扫码配对。
8. 清理旧数据：确认一切正常后，运行 hermes claw cleanup，将遗留的 OpenClaw 目录重命名为 .pre-migration/，防止状态混淆。

关键要点

• 预览优先机制：所有迁移操作默认先展示预览，防止误操作。使用 --dry-run 可安全检查。
• 多提供商简化：Hermes 通过 Portal 将多提供商 OAuth 整合为单一登录，支持 300+ 模型，简化了原本分散的配置。
• 密钥白名单限制：仅迁移特定白名单内的 API 密钥（如 OpenAI, Anthropic, Telegram 等），其他密钥不会自动复制。
• SecretRef 局限性：source: "file" 或 source: "exec" 类型的 SecretRef 无法自动解析，必须手动在 Hermes 中重新配置。