跳到主要内容

Openclaw 迁移

将用户的 OpenClaw 自定义配置迁移到 Hermes Agent。从 ~/.openclaw 导入与 Hermes 兼容的记忆、SOUL.md、命令允许列表、用户技能以及选定的工作区资产，然后准确报告无法迁移的内容及其原因。

技能元数据​

来源可选 — 使用 hermes skills install official/migration/openclaw-migration 安装
路径optional-skills/migration/openclaw-migration
版本1.0.0
作者Hermes Agent (Nous Research)
许可证MIT
标签Migration, OpenClaw, Hermes, Memory, Persona, Import
相关技能hermes-agent

参考：完整 SKILL.md​

信息

以下是 Hermes 在触发此技能时加载的完整技能定义。这是技能激活时代理所看到的指令。

OpenClaw -> Hermes 迁移

当用户希望以最少的手动清理工作将 OpenClaw 设置迁移到 Hermes Agent 时，请使用此技能。

CLI 命令​

对于快速、非交互式的迁移，请使用内置的 CLI 命令：

hermes claw migrate              # Full interactive migration
hermes claw migrate --dry-run    # Preview what would be migrated
hermes claw migrate --preset user-data   # Migrate without secrets
hermes claw migrate --overwrite  # Overwrite existing conflicts
hermes claw migrate --source /custom/path/.openclaw  # Custom source

该 CLI 命令运行下文所述的同一迁移脚本。当你希望通过代理进行交互式、引导式迁移，并包含预演（dry-run）预览和逐项冲突解决时，请使用此技能。

首次设置： hermes setup 向导会自动检测 ~/.openclaw，并在开始配置之前提供迁移选项。

此技能的功能​

它使用 scripts/openclaw_to_hermes.py 来：

  • 将 SOUL.md 导入到 Hermes 主目录，命名为 SOUL.md
  • 将 OpenClaw 的 MEMORY.md 和 USER.md 转换为 Hermes 记忆条目
  • 将 OpenClaw 命令批准模式合并到 Hermes 的 command_allowlist 中
  • 迁移与 Hermes 兼容的消息传递设置，例如 TELEGRAM_ALLOWED_USERS 和 MESSAGING_CWD
  • 将 OpenClaw 技能复制到 ~/.hermes/skills/openclaw-imports/
  • 可选地将 OpenClaw 工作区指令文件复制到指定的 Hermes 工作区
  • 镜像兼容的工作区资产，例如将 workspace/tts/ 复制到 ~/.hermes/tts/
  • 归档没有直接 Hermes 目标位置的非秘密文档
  • 生成结构化报告，列出已迁移项、冲突项、跳过项及原因

路径解析​

辅助脚本位于此技能目录下的：

  • scripts/openclaw_to_hermes.py

当从 Skills Hub 安装此技能时，正常位置为：

  • ~/.hermes/skills/migration/openclaw-migration/scripts/openclaw_to_hermes.py

不要猜测类似 ~/.hermes/skills/openclaw-migration/... 的较短路径。

在运行辅助脚本之前：

  1. 优先使用 ~/.hermes/skills/migration/openclaw-migration/ 下的已安装路径。
  2. 如果该路径失败，检查已安装的技能目录，并相对于已安装的 SKILL.md 解析脚本路径。
  3. 仅在已安装位置缺失或技能被手动移动时，才使用 find 作为后备方案。
  4. 调用终端工具时，不要传递 workdir: "~"。使用绝对目录（如用户的主目录），或完全省略 workdir。

使用 --migrate-secrets 时，它还将导入一小部分允许列表中的与 Hermes 兼容的秘密信息，目前包括：

  • TELEGRAM_BOT_TOKEN

默认工作流程​

  1. 首先通过预演（dry run）进行检查。
  2. 呈现简要摘要，说明可以迁移的内容、无法迁移的内容以及将被归档的内容。
  3. 如果 clarify 工具可用，则使用它来进行用户决策，而不是要求自由形式的文本回复。
  4. 如果预演发现导入的技能目录存在冲突，请在执行前询问如何处理这些冲突。
  5. 在执行前，要求用户在两种支持的迁移模式之间进行选择。
  6. 仅当用户希望迁移工作区指令文件时，才请求目标工作区路径。
  7. 使用匹配的预设和标志执行迁移。
  8. 总结结果，特别是：
    • 已迁移的内容
    • 已归档以供手动审查的内容
    • 已跳过的内容及其原因

用户交互协议​

Hermes CLI 支持用于交互式提示的 clarify 工具，但其功能限于：

  • 每次选择一个选项
  • 最多 4 个预定义选项
  • 一个自动的 Other 自由文本选项

它不支持在单个提示中进行真正的多选复选框操作。

对于每次 clarify 调用：

  • 始终包含非空的 question
  • 仅在真正的可选择提示中包含 choices
  • 将 choices 限制为 2-4 个纯字符串选项
  • 切勿发出占位符或截断的选项，例如 ...
  • 切勿用额外的空白字符填充或美化选项
  • 切勿在问题中包含虚假的表单字段，例如 enter directory here、待填写的空白行或下划线（如 _____）
  • 对于开放式路径问题，仅提出简单的句子；用户在面板下方的正常 CLI 提示中输入内容

如果 clarify 调用返回错误，请检查错误文本，修正 payload，并使用有效的 question 和干净的选项重试一次。

当 clarify 可用且预运行（dry run）揭示任何需要用户决策的事项时，你的下一步操作必须是调用 clarify 工具。

不要以普通的助手消息结束当前回合，例如：

  • “让我展示选项”
  • “你想做什么？”
  • “以下是可选方案”

如果需要用户决策，请在生成更多正文之前通过 clarify 收集该决策。 如果存在多个未解决的决策，不要在它们之间插入解释性的助手消息。在收到一个 clarify 响应后，你的下一步操作通常应该是下一个所需的 clarify 调用。

每当预运行报告以下内容时，将 workspace-agents 视为未解决的决策：

  • kind="workspace-agents"
  • status="skipped"
  • 原因包含 No workspace target was provided

在这种情况下，你必须在执行前询问关于工作区指令的事项。不要静默地将其视为跳过决策。

由于该限制，请使用此简化决策流程：

  1. 对于 SOUL.md 冲突，使用 clarify 并提供如下选项：
    • keep existing
    • overwrite with backup
    • review first
  2. 如果预运行显示一个或多个 kind="skill" 项的 status="conflict"，使用 clarify 并提供如下选项：
    • keep existing skills
    • overwrite conflicting skills with backup
    • import conflicting skills under renamed folders
  3. 对于工作区指令，使用 clarify 并提供如下选项：
    • skip workspace instructions
    • copy to a workspace path
    • decide later
  4. 如果用户选择复制工作区指令，请提出后续开放式 clarify 问题，请求提供绝对路径。
  5. 如果用户选择 skip workspace instructions 或 decide later，请在不使用 --workspace-target 的情况下继续。
  6. 对于迁移模式，使用 clarify 并提供以下 3 个选项：
    • user-data only
    • full compatible migration
    • cancel
  7. user-data only 意味着：迁移用户数据和兼容配置，但不导入允许列表中的密钥（secrets）。
  8. full compatible migration 意味着：迁移相同的兼容用户数据以及存在时的允许列表中的密钥。
  9. 如果 clarify 不可用，请以普通文本询问相同的问题，但仍将答案限制为 user-data only、full compatible migration 或 cancel。

执行门禁：

  • 当由 No workspace target was provided 引起的 workspace-agents 跳过状态仍未解决时，不要执行。
  • 解决该问题的唯一有效方式是：
    • 用户明确选择 skip workspace instructions
    • 用户明确选择 decide later
    • 用户在选择 copy to a workspace path 后提供了工作区路径
  • 预运行中缺少工作区目标本身并不构成执行的许可。
  • 当任何所需的 clarify 决策仍未解决时，不要执行。

使用以下确切的 clarify 负载结构作为默认模式：

  • {"question":"Your existing SOUL.md conflicts with the imported one. What should I do?","choices":["keep existing","overwrite with backup","review first"]}
  • {"question":"One or more imported OpenClaw skills already exist in Hermes. How should I handle those skill conflicts?","choices":["keep existing skills","overwrite conflicting skills with backup","import conflicting skills under renamed folders"]}
  • {"question":"Choose migration mode: migrate only user data, or run the full compatible migration including allowlisted secrets?","choices":["user-data only","full compatible migration","cancel"]}
  • {"question":"Do you want to copy the OpenClaw workspace instructions file into a Hermes workspace?","choices":["skip workspace instructions","copy to a workspace path","decide later"]}
  • {"question":"Please provide an absolute path where the workspace instructions should be copied."}

决策到命令的映射​

将用户决策精确映射到命令标志：

  • 如果用户为 SOUL.md 选择 keep existing，不要添加 --overwrite。
  • 如果用户选择 overwrite with backup，添加 --overwrite。
  • 如果用户选择 review first，在执行前停止并审查相关文件。
  • 如果用户选择 keep existing skills，添加 --skill-conflict skip。
  • 如果用户选择 overwrite conflicting skills with backup，添加 --skill-conflict overwrite。
  • 如果用户选择 import conflicting skills under renamed folders，添加 --skill-conflict rename。
  • 如果用户选择 user-data only，使用 --preset user-data 执行，并且不要添加 --migrate-secrets。
  • 如果用户选择 full compatible migration，使用 --preset full --migrate-secrets 执行。
  • 仅当用户明确提供了绝对工作区路径时，才添加 --workspace-target。
  • 如果用户选择 skip workspace instructions 或 decide later，不要添加 --workspace-target。

在执行之前，用通俗语言重述确切的命令计划，并确保它与用户的选择一致。

运行后报告规则​

执行后，将脚本的 JSON 输出视为真实来源。

  1. 所有计数均基于 report.summary。
  2. 仅当某项的 status 恰好为 migrated 时，才将其列在“成功迁移”下。
  3. 除非报告显示该项为 migrated，否则不要声称冲突已解决。
  4. 除非 kind="soul" 的报告项具有 status="migrated"，否则不要说 SOUL.md 已被覆盖。
  5. 如果 report.summary.conflict > 0，请包含一个冲突部分，而不是静默地暗示成功。
  6. 如果计数与列出的项目不一致，请在响应之前修正列表以匹配报告。
  7. 在可用时包含报告中的 output_dir 路径，以便用户可以检查 report.json、summary.md、备份和归档文件。
  8. 对于内存或用户配置文件溢出，除非报告明确显示归档路径，否则不要说条目已归档。如果存在 details.overflow_file，请说明完整的溢出列表已导出到该位置。
  9. 如果技能是在重命名的文件夹下导入的，请报告最终目标位置并提及 details.renamed_from。
  10. 如果存在 report.skill_conflict_mode，请将其用作所选导入技能冲突策略的真实来源。
  11. 如果某项的 status="skipped"，不要将其描述为已覆盖、已备份、已迁移或已解决。
  12. 如果 kind="soul" 的 status="skipped" 且原因为 Target already matches source，请说明其保持未变，并且不要提及备份。
  13. 如果重命名的导入技能的 details.backup 为空，不要暗示现有的 Hermes 技能已被重命名或备份。仅说明导入的副本已放置在新目标位置，并引用 details.renamed_from 作为保留在原位的现有文件夹。

迁移预设​

在正常使用时，首选以下两个预设：

  • user-data
  • full

user-data 包括：

  • soul
  • workspace-agents
  • memory
  • user-profile
  • messaging-settings
  • command-allowlist
  • skills
  • tts-assets
  • archive

full 包括 user-data 中的所有内容，外加：

  • secret-settings

辅助脚本仍然支持类别级别的 --include / --exclude，但应将其视为高级后备方案，而非默认的用户体验。

命令​

进行完整发现的干跑（dry run）：

python3 ~/.hermes/skills/migration/openclaw-migration/scripts/openclaw_to_hermes.py

使用终端工具时，首选绝对调用模式，例如：

{"command":"python3 /home/USER/.hermes/skills/migration/openclaw-migration/scripts/openclaw_to_hermes.py","workdir":"/home/USER"}

使用 user-data 预设进行干跑：

python3 ~/.hermes/skills/migration/openclaw-migration/scripts/openclaw_to_hermes.py --preset user-data

执行 user-data 迁移：

python3 ~/.hermes/skills/migration/openclaw-migration/scripts/openclaw_to_hermes.py --execute --preset user-data --skill-conflict skip

执行完全兼容的迁移：

python3 ~/.hermes/skills/migration/openclaw-migration/scripts/openclaw_to_hermes.py --execute --preset full --migrate-secrets --skill-conflict skip

执行时包含工作区指令：

python3 ~/.hermes/skills/migration/openclaw-migration/scripts/openclaw_to_hermes.py --execute --preset user-data --skill-conflict rename --workspace-target "/absolute/workspace/path"

默认情况下，不要使用 $PWD 或主目录作为工作区目标。首先询问明确的工作区路径。

重要规则​

  1. 除非用户明确指示立即继续，否则在写入之前先运行干跑。
  2. 默认情况下不要迁移机密。令牌、身份验证 blob、设备凭据和原始网关配置应保留在 Hermes 之外，除非用户明确要求迁移机密。
  3. 除非用户明确希望如此，否则不要静默覆盖非空的 Hermes 目标。启用覆盖时，辅助脚本将保留备份。
  4. 始终向用户提供跳过项目的报告。该报告是迁移的一部分，而非可选的额外内容。
  5. 首选主要的 OpenClaw 工作区（~/.openclaw/workspace/），而非 workspace.default/。仅当主要文件缺失时，才将默认工作区作为后备使用。
  6. 即使在机密迁移模式下，也仅将机密迁移到干净的 Hermes 目标位置。不支持的身份验证 blob 仍必须报告为已跳过。
  7. 如果干跑显示大量资产复制、冲突的 SOUL.md 或溢出的内存条目，请在执行之前单独指出这些问题。
  8. 如果用户不确定，默认选择“仅 user-data”。
  9. 仅当用户明确提供了目标工作区路径时，才包含 workspace-agents。
  10. 将类别级别的 --include / --exclude 视为高级逃生舱口，而非常规流程。
  11. 如果可以使用 clarify，不要在干跑总结末尾使用模糊的“您想做什么？”。改用结构化的后续提示。
  12. 当真正的选择提示起作用时，不要使用开放式的 clarify 提示。首选可选择的选项，然后仅对绝对路径或文件审查请求使用自由文本。
  13. 干跑后，如果仍有未解决的决策，切勿在总结后停止。立即对最高优先级的阻塞性决策使用 clarify。
  14. 后续问题的优先级顺序：
    • SOUL.md 冲突
    • 导入的技能冲突
    • 迁移模式
    • 工作区指令目标位置
  15. 不要承诺在同一消息中稍后提供选项。通过实际调用 clarify 来呈现它们。
  16. 在回答迁移模式后，明确检查 workspace-agents 是否仍未解决。如果是，您的下一个操作必须是工作区指令的 clarify 调用。
  17. 在任何 clarify 回答之后，如果还有其他必需的决策待定，不要叙述刚刚决定的内容。立即询问下一个必需的问题。

预期结果​

成功运行后，用户应拥有：

  • 已导入 Hermes 角色状态
  • 已使用转换后的 OpenClaw 知识填充 Hermes 内存文件
  • OpenClaw 技能可在 ~/.hermes/skills/openclaw-imports/ 下使用
  • 一份迁移报告，显示任何冲突、遗漏或不支持的数据