SuperAPI AI 工具集

openclaw-migration

编程与开发

查看项目

更新于 11-09 20:22

技能介绍

用途

openclaw-migration 用于把用户已有的 OpenClaw 配置迁移进 Hermes Agent,目标是尽量减少手工清理。它属于 nousresearch/hermes-official-plugins 仓库,由 agent-importers 插件提供。

主要能力

迁移脚本 scripts/openclaw_to_hermes.py 可完成以下工作:

  • 将 SOUL.md 导入 Hermes 主目录,作为 SOUL.md;
  • 把 OpenClaw 的 MEMORY.md 和 USER.md 转换为 Hermes 记忆条目;
  • 将 OpenClaw 的命令审批模式合并到 Hermes 的 command_allowlist;
  • 迁移 Hermes 兼容的消息设置(例如 TELEGRAM_ALLOWED_USERS),并把 OpenClaw 工作区目录映射为 config.yaml 中的 terminal.cwd;
  • 把 OpenClaw 技能复制到 ~/.hermes/skills/openclaw-imports/;
  • 可选地把 OpenClaw 工作区说明文件复制到指定的 Hermes 工作区;
  • 镜像兼容的工作区资产,例如把 workspace/tts/ 复制到 ~/.hermes/tts/;
  • 归档没有直接 Hermes 目标的非密钥文档;
  • 生成结构化报告,列出已迁移项、冲突、跳过项及原因。

启用 --migrate-secrets 后,还会导入白名单内的一小组 Hermes 兼容密钥,目前为 TELEGRAM_BOT_TOKEN。

使用方式

CLI 命令

agent-importers 插件提供以下快速、非交互式命令:

  • hermes import-agent openclaw:完整交互式迁移
  • hermes import-agent openclaw --dry-run:预览将迁移的内容
  • hermes import-agent openclaw --preset user-data:不迁移密钥
  • hermes import-agent openclaw --overwrite:覆盖已有冲突
  • hermes import-agent openclaw --source /custom/path/.openclaw:自定义来源

旧写法 hermes claw migrate(参数相同)仍可用;hermes claw cleanup 会在之后归档遗留的 OpenClaw 目录。CLI 命令运行的是与下文相同的迁移脚本。若需要交互式引导、dry-run 预览和逐项冲突处理,则通过 agent 使用本技能。

首次设置时,hermes setup 会提供从其他 agent(OpenClaw、Claude Code、Codex CLI、Cursor)导入的选项。

直接运行脚本

使用 Hermes 的 Python 环境(其中包含 ruamel.yaml);独立 Python 环境需先安装 ruamel.yaml==0.18.17。

以下命令中 <skill-dir> 是存放本 SKILL.md 的绝对目录:

  • 完整发现式 dry run:python <skill-dir>/scripts/openclaw_to_hermes.py
  • user-data 预设 dry run:python <skill-dir>/scripts/openclaw_to_hermes.py --preset user-data
  • 执行 user-data 迁移:python <skill-dir>/scripts/openclaw_to_hermes.py --execute --preset user-data --skill-conflict skip
  • 执行 full 兼容迁移:python <skill-dir>/scripts/openclaw_to_hermes.py --execute --preset full --migrate-secrets --skill-conflict skip
  • 包含工作区说明文件的执行:python <skill-dir>/scripts/openclaw_to_hermes.py --execute --preset user-data --skill-conflict rename --workspace-target "/absolute/workspace/path"

使用终端工具时,建议采用绝对路径调用,例如:{"command":"python /absolute/path/to/openclaw-migration/scripts/openclaw_to_hermes.py","workdir":"/home/USER"}。不要将 workdir 设为 "~"。

迁移预设

常规使用建议采用两种预设:

  • 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 检查,向用户给出可迁移、不可迁移和将被归档内容的简要汇总;若存在需要用户决定的事项,使用 clarify 工具收集选择(每次一个问题、2 至 4 个预定义选项、附带 Other 自由输入,不支持多选)。若 clarify 不可用,则以普通文本提出同样的问题,并把回答限定在给定选项内。

主要决策及其命令映射:

  • SOUL.md 冲突:保留现有(不加 --overwrite);覆盖并备份(加 --overwrite);先审阅(停止执行并检查文件)。
  • 技能冲突:保留现有技能(--skill-conflict skip);覆盖冲突技能并备份(--skill-conflict overwrite);以重命名文件夹导入冲突技能(--skill-conflict rename)。
  • 迁移模式:仅用户数据(--preset user-data,不加 --migrate-secrets);完整兼容迁移(--preset full --migrate-secrets);取消。
  • 工作区说明文件:跳过或稍后决定都不加 --workspace-target;选择复制时,需再询问一个绝对路径,并且只有用户明确提供路径后才加 --workspace-target。

若 dry run 报告 kind="workspace-agents" 且 status="skipped"、原因包含 "No workspace target was provided",这属于未解决决策,必须先询问用户,不能当作自动跳过而直接执行。存在任何未解决的必需决策时,不应执行迁移。

执行后报告

执行后以脚本输出的 JSON 为唯一事实来源:计数基于 report.summary;只有状态为 migrated 的条目才能列为“已成功迁移”;report.summary.conflict 大于 0 时应单列冲突部分;若提供 output_dir,应告知用户可查看 report.json、summary.md、备份与归档文件;记忆或用户档案溢出时,只有在 details.overflow_file 存在时才能说完整溢出列表已导出到该处;重命名导入的技能应报告最终位置并说明 details.renamed_from;状态为 skipped 的条目不得描述为已覆盖、已备份或已解决。

适用场景

适合希望把 OpenClaw 中积累的人格设定、记忆、命令审批规则、消息设置、技能与工作区资产迁移到 Hermes Agent,并希望先预览、按需选择覆盖策略与是否迁移密钥的用户。

限制与注意事项

  • 执行前应先 dry run,除非用户明确要求立即执行。
  • 默认不迁移密钥;令牌、认证数据、设备凭据和原始网关配置不应进入 Hermes,除非用户明确要求迁移密钥;即使启用密钥迁移,也只迁移有干净 Hermes 目标的密钥,不支持的数据须报告为跳过。
  • 不得静默覆盖非空的 Hermes 目标;启用覆盖时应保留备份。
  • 必须向用户提供跳过项报告。
  • 优先使用主 OpenClaw 工作区(~/.openclaw/workspace/)而非 workspace.default/,仅当主工作区文件缺失时才回退。
  • 不应默认把 $PWD 或主目录作为工作区目标,需先询问明确路径。
  • dry run 若发现大量资产复制、SOUL.md 冲突或记忆条目溢出,应在执行前单独说明。
  • 用户不确定时默认仅迁移 user-data。
  • 迁移完成后,用户应获得已导入的人格状态、填入转换后知识的内存文件、位于 ~/.hermes/skills/openclaw-imports/ 的 OpenClaw 技能,以及一份列出冲突、遗漏和不支持数据的迁移报告。