从 OpenClaw 迁到 Hermes 这件事我本来是不太感冒的。做智能体最怕的不是写功能而是换底座。OpenClaw 用得顺手技能、记忆、工具调用全都跑得好好的迁移意味着什么重写配置、重接 API、重测对话链路想想就头大。直到把整个流程跑通之后我承认自己之前的判断有点保守只要把资产清点清楚、转换规则定明白一条命令完成迁移并不是宣传话术而是确实可行的操作。这篇文章我会完整复盘这套迁移方案。从 OpenClaw 的目录结构和配置格式说起讲到 Hermes 的模型差异、迁移命令的内部执行链路再到迁移完成后最容易翻车的记忆数据和工具签名问题。如果你也在评估从 OpenClaw 迁移到 Hermes或者手头正好有一个跑在 OpenClaw 上的老智能体这篇文章可以直接当成操作手册来用。1. 迁移的核心逻辑两个框架到底差异在哪不管迁移工具写得多智能一条命令背后一定是明确的映射关系。所以先别急着敲命令得先搞清楚 OpenClaw 和 Hermes 的资产模型之间的对应关系。这一节不涉及具体配置代码但却是整个迁移方案的地基。1.1 OpenClaw 的资产组织方式OpenClaw 的目录结构非常自由一个典型的项目大概长这样my-agent/ ├── claw.yaml ├── skills/ │ ├── weather/ │ │ ├── SKILL.md │ │ └── tools.py │ └── calendar/ ├── tools/ │ └── custom_tool.py ├── memory/ │ ├── long_term.db │ └── sessions/ └── .envclaw.yaml是总配置负责声明系统提示词、模型参数、工具启用开关。技能放在skills/目录下每个技能用一个SKILL.md描述用途和触发条件配套代码负责执行。工具则是更底层的函数调用直接对接外部 API 或本地命令。这种组织方式很轻量但对于稍大一点的项目容易出现一个问题技能的触发逻辑散落在SKILL.md的描述文本里没有统一的函数调用规范。当技能数量超过十个以后智能体经常出现工具存在但调不对参数的情况。1.2 Hermes 的资产组织方式Hermes 在结构上更强调显式声明。它的配置文件是hermes.toml技能和插件分开管理hermes-agent/ ├── hermes.toml ├── agents/ │ └── default.yaml ├── plugins/ │ ├── weather/ │ │ ├── manifest.toml │ │ └── handler.py ├── skills/ │ └── calendar.md ├── memory/ │ └── vector_store/ └── .envHermes 的插件机制要求每个插件在manifest.toml里用 JSON Schema 声明完整的函数签名包括参数类型、必填项、返回结构。这个设计在迁移阶段确实是额外工作量但从长远看它让工具调用变得可校验、可观测智能体不会再凭猜测传参。1.3 一条命令能成立的前提条件迁移工具能把 OpenClaw 的项目转成 Hermes 项目本质上做了三件事把claw.yaml的字段映射到hermes.toml和agents/default.yaml把skills/SKILL.md的触发描述改写成 Hermes 的 skill 格式把tools/*.py里松散定义的函数包装成带 JSON Schema 的插件所以一条命令听起来简单但它的准确性完全取决于上游资产的规范程度。OpenClaw 项目如果本身结构混乱迁移工具再强也无能为力。这也是为什么我在执行迁移之前花了整整一个下午做资产清点。2. 动手前的资产清点与备份检查迁移最怕的不是丢功能而是丢状态。代码可以重写但智能体积累的长期记忆、用户偏好、历史会话上下文这些是没办法凭空重建的。所以迁移前的清点和备份是整个流程里我最重视的部分宁可多花时间也不能跳过。2.1 需要迁移的内容清单我整理了一个五类清单每一类对应不同的迁移策略资产类型OpenClaw 位置迁移策略风险等级全局配置claw.yaml字段映射后写入hermes.toml低技能定义skills/*/SKILL.md重写触发描述 保留代码中自定义工具tools/*.py包装为插件并补充 JSON Schema高记忆数据memory/long_term.db读取后重新写入向量库高凭据与密钥.env直接复制并核对变量名低但易漏这里要特别提醒很多人清点的时候只盯着配置和代码忽略了.env。实际上 OpenClaw 和 Hermes 对环境变量的命名规范不完全一样比如 OpenClaw 里的OPENCLAW_MODEL_TEMP在 Hermes 里可能需要改成HERMES_MODEL_TEMP如果不做一次完整核对迁移后智能体可能直接失去模型访问能力。2.2 备份与冻结检查我执行迁移之前做了两步操作。第一步是完整备份 OpenClaw 项目目录连同数据库文件一起打包。第二步是把正在运行的 OpenClaw 智能体切换到只读模式避免迁移过程中产生新的会话数据导致前后不一致。备份命令很简单tar -czvf openclaw-backup-$(date %Y%m%d).tar.gz ./my-agent/但这里有一个细节如果 OpenClaw 正在运行long_term.db可能有未落盘的数据。我先通过 OpenClaw 的管理接口触发了一次显式会话落盘确认日志中提示memory checkpoint complete之后才执行打包。这个操作虽然不起眼却避免了备份文件里的数据库是旧版本的问题。另一个值得记录的检查点是确认 OpenClaw 项目的 Python 环境和依赖锁定文件。因为 Hermes 的插件体系要求每个插件声明自己的依赖迁移工具无法自动解析 OpenClaw 项目requirements.txt中哪些依赖属于哪个技能所以我会先在项目根目录跑一次pipreqs生成依赖映射这样在生成 Hermes 插件manifest.toml时可以手动对照着补充依赖声明。2.3 迁移前的一次核心对话审查在真正动工具之前我还做了一件很多人想不到的事把当前 OpenClaw 智能体最近二十轮真实对话导出作为迁移后的验收基准。这些对话记录了模型是怎么调用工具的、工具返回了什么格式、智能体如何基于工具结果继续对话。迁移完成后我会用同样的输入跑一遍 Hermes对比输出质量。这一步的价值在于它把迁移是否成功从一个模糊的感受变成了可量化的标准。配置可以转换成功工具可以全部注册成功但如果迁移后智能体的对话风格或者工具调用策略发生了变化那依然是一次不完整的迁移。3. 一条命令背后的四段执行链路准备工作做完才轮到主角登场。我用的迁移工具是hermes-migrate执行方式很直接hermes-migrate --src ./my-agent --dst ./hermes-agent --apply如果不对配置结构完全放心可以先加--dry-run参数做一次预演。我实际跑下来发现这工具比我想象中靠谱但前提是理解它内部到底怎么工作。拆开来看这条命令背后是扫描、转换、导入、校验四个阶段。3.1 扫描阶段读取 OpenClaw 资产并生成索引迁移工具首先遍历src目录识别出claw.yaml、技能目录、工具目录和记忆数据库生成一个资产索引树。这个阶段我发现它会主动跳过一些明显无关的文件比如.git和__pycache__但如果有自定义的子目录放了一堆非标准技能文件扫描器可能会漏掉。如果在--dry-run的输出里发现某个技能没有出现在扫描结果中不用怀疑工具坏了先检查那个技能目录下有没有SKILL.md文件。OpenClaw 允许技能目录里只有代码文件没有说明文件这种情况迁移工具无法识别它是一个技能确实需要手动加入。3.2 转换阶段逐类资产的映射转换阶段是技术含量最高的部分分三条线并行处理。第一线是配置映射。claw.yaml里的模型参数、系统提示词、temperature、max_tokens 等一一对应到 Hermes 的agents/default.yaml。有些字段不能直接对应比如 OpenClaw 的tool_timeout在 Hermes 里变成了插件的独立超时参数转换工具会给出 warning 而不是直接报错因为这是一处可以用但不完全等价的映射。第二线是技能改写。SKILL.md中的触发条件和行为描述会被改写成 Hermes 支持的 skill 格式包括name、description、trigger三个字段。这里我发现转换工具对中文描述的支持不错但技能的触发关键词如果写得太泛比如帮我看一下转换后 Hermes 可能无法正确匹配到对应技能。需要手动调整触发词。第三线是工具包装。这是最容易出问题的环节。OpenClaw 的自定义工具通常是裸 Python 函数没有参数 schema。转换工具会尝试通过函数的__annotations__和默认值推断参数类型自动生成 JSON Schema但对复杂结构嵌套对象、可选参数、泛型的推断经常不准确迁移后会出现参数格式校验失败。3.3 导入阶段写入 Hermes 目录结构导入阶段的工作相对机械把转换后的配置写入hermes.toml把技能和插件写入对应目录把.env的内容复制并做变量名映射。这个阶段最需要注意的是凭据导入工具会读取 OpenClaw 的.env但不会自动识别所有自定义变量。它只保证OPENCLAW_API_KEY这类带前缀的变量名能被转换纯自定义的变量名比如MY_SERVICE_TOKEN会原样保留但不会做任何校验。导入完成后工具会输出一份清单明确列出哪些配置项被自动映射、哪些需要人工确认。我强烈建议不要跳过这份清单直接开始测对话因为里面经常藏着关键信息。3.4 校验阶段静态检查与依赖核对最后一步是校验。工具会检查生成的 Hermes 项目配置是否能被hermes命令正常解析插件目录下每个manifest.toml是否包含合法的 JSON Schema以及记忆数据库是否成功导入。静态校验通过不代表运行完全没问题。比如工具依赖缺失这类问题校验阶段只能通过检查manifest.toml中声明的依赖是否存在于项目环境中来发现但模型运行时会加载哪些依赖有时只有真正调用工具的那一刻才会暴露。所以我在迁移完成后还会额外跑一轮针对性验证这部分在下一节详细展开。4. 迁移完成后的数据验证与适配调整迁移命令执行完毕后dst目录下已经生成了一套完整的 Hermes 项目。这时候千万别急着删掉 OpenClaw 的原始目录至少保留一周作为回退方案。真正的工作其实刚刚开始——验证迁移的完整性处理那些需要手动调整的适配点。4.1 配置与模型参数的首轮验证我用hermesCLI 直接启动迁移后的智能体观察启动日志里是否有配置解析警告。这里我实际碰到过一个问题OpenClaw 的claw.yaml里定义的model_config包括一段自定义的response_format转换工具不太确定 Hermes 对应字段的写法于是把它原样复制成了一个不存在的字段。Hermes 启动时报了unrecognized configuration key但报错信息隐藏在日志深处不仔细看会忽略掉。排查方法很简单打开agents/default.yaml逐项核对模型参数。重点看temperature、top_p、max_tokens这几个参数是否被正确映射以及stop_sequences这类 OpenClaw 特有的字段是否已经被转换工具对应到 Hermes 的等价表达。对照 OpenClaw 的原始配置逐项过一遍大概五分钟就能确认完毕。4.2 工具调用签名最隐蔽的坑迁移过程中我遇到的最棘手问题就是自定义工具的签名校验。OpenClaw 的项目里有一个日历查询工具核心代码长这样def query_calendar(start_date: str, end_date: str None, category: str all) - list: ...转换工具为它生成的 JSON Schema 大概是这样的{ type: object, properties: { start_date: {type: string}, end_date: {type: string}, category: {type: string, default: all} }, required: [start_date] }问题出在end_date参数。OpenClaw 里允许不传这个参数函数内部会默认取当前日期。但在 Hermes 里插件系统调用工具时会严格按 JSON Schema 校验如果模型没有收到明确的提示说end_date可选它有时候会自作聪明地补一个格式错误的日期字符串导致函数内部解析失败。解决办法是在manifest.toml里给end_date加上更明确的描述字段比如description: 结束日期不传时默认使用今天并且把default值显式标注为null。这样模型在生成参数时会参考描述文本传错参数的概率大幅下降。4.3 记忆数据迁移后的容量与召回检查OpenClaw 的记忆数据库是 sqliteHermes 的默认记忆后端是向量数据库。迁移工具做的事情是读取 sqlite 中的历史会话记录逐条向量化后写入 Hermes 的向量库。这个过程的耗时取决于数据量我的项目里大约有两百多万字符的对话记录转换过程跑了大概四十分钟。转换完成后一定要做的检查是召回验证——随机选几个历史对话片段作为查询看 Hermes 能否正确检索到相关的上下文。我测的时候发现一个问题有一些早期对话记录在 OpenClaw 中只有纯文本存储没有元数据标记导入 Hermes 后向量检索的结果在某些查询词下会偏差比较大。这大概率是分块策略不一致导致的解决方法是在 Hermes 配置中调整检索时的top_k参数从默认的 3 提到 5同时把distance_threshold放宽一些。这种调整不能机械复刻得根据实际召回结果来定。4.4 技能触发效果的对比验证技能迁移后不能只看SKILL.md是否转换成功要看触发效果是否一致。我的做法是拿迁移前保存的二十轮真实对话回放到 Hermes 智能体上观察每个技能是否在同样的位置被触发。实测发现OpenClaw 项目里的一个天气查询技能原来通过今天天气怎么样需要带伞吗这类自然语言触发转换到 Hermes 后工具自动把触发方式改成了关键词匹配后天会下雨吗这种表述触发了另一个技能。这是因为转换工具在改写trigger字段时只取了SKILL.md里写明的第一个触发词没有综合理解整个描述。这类问题没有自动解法只能手动修正skills/weather.md里的 trigger 表达式补充同义表达和否定句式。5. 高频报错与排查实录迁移过程中踩过的坑不少我把最典型的几个问题整理成一张速查表对应的解决方案都是实际验证过的。现象根因解决方案迁移工具扫描不到某个技能技能目录缺少SKILL.md手动补一个说明文件后重新扫描Hermes 启动报 unrecognized key配置字段映射不完全在default.yaml中删除或重写该字段工具调用频繁参数校验失败JSON Schema 缺少描述和默认值检查manifest.toml为参数补充 description模型找不到任何技能trigger 表达式过于严格在技能文件中补充同义触发词历史记忆召回效果差分块策略与元数据不匹配调整top_k和distance_threshold参数自定义 API 密钥没生效OpenClaw 环境变量未转换为 Hermes 命名对照.env手动补充变量5.1 迁移工具报技能目录结构异常这是我遇到的第一个报错。原因是我有一个技能目录里既有SKILL.md又有子目录python_tools/扫描器识别不了这种嵌套结构。解法比较粗暴把子目录里的模块作为独立工具拆出来单独处理然后修改SKILL.md的描述指向新的调用方式。5.2 模型一调用工具就卡死迁移后测试对话时模型一调用邮件发送工具就卡住不动最后超时。排查发现是插件manifest.toml里声明的依赖版本和 Hermes 运行环境的版本冲突——OpenClaw 项目用的是requests 2.31而 Hermes 插件环境默认装的是2.32。这个问题的教训是依赖锁定必须显式写入插件声明不能指望转换工具自动识别。5.3 迁移后模型失忆有段时间我怀疑记忆迁移失败了因为智能体完全想不起来用户之前提到的一个项目编号。翻日志发现OpenClaw 把记忆数据按时间分片存储而迁移工具没有处理分片顺序导致部分片段被重复写入向量库检索时被重复片段干扰。清理完重复向量之后召回就恢复正常了。6. 我的一些实战经验与建议整个迁移从准备到完全跑通我实际花了大约两天时间其中真正执行hermes-migrate命令的时间不到五分钟。剩下的时间全部花在了资产清点、配置核对和记忆召回验证上。这让我对一条命令迁移有了更真实的认知一条命令可以帮你完成繁重的转换工作但决定迁移质量的永远是迁移之前对现有资产的梳理以及迁移之后对关键链路的验证。几点具体的建议先做小范围试点别直接迁移生产智能体。我是在一个模拟项目上先跑通了一套迁移流程确认转换工具的映射规则符合预期才正式应用到真实项目。这个模拟项目特意构造了一些非标准的技能结构比如无说明文件的技能、带复杂参数的函数、格式不规范的中文技能描述。通过测试我提前发现了三种转换工具的边界情况避免了正式迁移时手忙脚乱。迁移后的第一次对话测试不要让模型自由发挥。我在验收时会构造一批固定指令比如查询今天的日程调用天气工具回顾昨天讨论过的方案逐条观察工具调用是否正确、参数是否按预期传递。只有这些基础调用全部正常才进入开放式对话测试。保留迁移日志它是最好的文档。hermes-migrate执行后生成的迁移报告里记录了每一个映射操作和警告信息。我在一周后回看这份报告发现有几处当时忽略的小提示正好对应后来出现的两个隐性配置问题。这些日志不仅是排查故障的线索也是团队其他成员理解本次迁移过程的第一手资料。最后再分享一个小技巧迁移后我在 Hermes 项目根目录保留了一个MIGRATION_NOTES.md把清点清单、手动调整点、未自动转换的配置项全部记录在案。这样一个月后如果发现某个技能调用异常不用重新翻两个框架的文档直接看这份笔记就能定位问题。这种习惯比任何迁移工具都更能保证一个长期项目的可维护性。