小龙虾OpenClaw 迁移 Hermes Agent:踩过的三个坑

最近把 OpenClaw 迁移到 Hermes Agent，两个框架的逻辑差异不小。迁移完的 skills 和配置还需要磨合，原先的 playbook 编排不能通用，得转换成 skill。这篇文章记录迁移过程中踩过的三个坑，以及最终的解法。

为什么要迁移

先说说动机。OpenClaw 用了挺长一段时间，功能不差，但几个问题越来越让人头疼。

首先是成本。 OpenClaw 每次启动都要加载全部记忆和上下文，token 消耗不小。Hermes 不一样，它有分层的记忆机制——长期记忆、会话记忆、skill 各管各的，系统提示词始终精简。跑同样的任务，token 开销明显更低。

其次是稳定性。 OpenClaw 的更新节奏很快，但发版质量参差不齐，时不时一个版本更新就导致整个流程不可用。对于依赖 AI Agent 日常干活的人来说，这种不确定性很致命。Hermes 这边工程化做得更扎实，版本迭代稳定，配置和接口的兼容性也好得多。相比之下，OpenClaw 有点草台班子的感觉。

最后是生态和可追踪性。 Hermes 支持多种模型（OpenRouter 200+ 模型、智谱、Kimi、MiniMax 等），接入 Grok 的 TTS 也非常顺滑。OpenClaw 和 Hermes 都是开源项目，遇到问题可以直接看源码定位，不用瞎猜。但 Hermes 的代码组织更清晰，配置链路更容易追踪，这一点在排查问题的时候感受特别明显。

整个迁移过程交给 Codex APP（OpenAI 的 Codex 应用，不是终端命令行的 Codex CLI）来操刀。给它一个指令：分析 OpenClaw 的配置和 skill，迁移到 Hermes，同时保留 OpenClaw 后面可以启动的能力。Codex 完成了大部分文件迁移工作。

但迁移完成不等于万事大吉。后面三个坑都是在迁移完成后，验证复原原来的功能时遇到的——文件搬过来了，能力没跟上。排查过程主要是借助 Hermes 自己来完成的：让它读日志、查源码、分析配置链路，定位到问题根因。有些操作 Hermes 受安全机制限制无法直接执行（比如写 .env 文件会被拦截），就由我手动补充参数来处理。人机协作，各取所长。

先搞清楚一个概念：Playbook

在讲坑之前，需要解释一下「Playbook 编排」这个概念，因为迁移中最大的隐性工作就是它的转换。

Playbook 翻译过来就是「剧本」或「编排」。简单说，它是在某个场景中完成一系列动作的流水线和判断流程。举个例子，一篇文章从写作到发布，涉及的环节包括：素材整理、起标题、风格润色、配图、封面生成、发布。每个环节都可能调用不同的 skill——配图有手动传图和 Agent 自动分析信息密度生成配图提示词两种方式；发布要看目标平台，发飞书用飞书 skill，发公众号用 baoyu-post-to-wechat skill。

这些不同的场景和分支组合起来，形成不同的编排路径。在 OpenClaw 里，playbook 以 .md 文件的形式存在，记录在 memory 或角色职责中，通过路由器执行。迁移到 Hermes 后，playbook 的概念变成了 skill——每个 skill 有自己的目录结构（SKILL.md + scripts/references/templates），编排逻辑不能直接通用，需要逐一适配。

这不是简单改个文件格式的事，而是两套编排体系的范式转换。

一切从迁移开始

有了上面的背景，回到迁移本身。迁移的第一步是把 skills 和配置搬过来，然后逐个验证功能。结果发现，光把文件搬过来远远不够，很多能力需要重新配置才能跑起来。

下面按踩坑的顺序，一个一个说。

坑一：联网搜索，API Key 没了

迁移完第一次运行检查命令，发现联网搜索完全不可用。Hermes 支持好几个搜索 provider（Brave、Tavily、Exa 等），但一个都没配上。

在 OpenClaw 里，Brave Search 的 API Key 存放在配置文件 openclaw.json 的 tools.web.search.apiKey 字段，迁移时这些配置不会自动带过来。Hermes 需要的环境变量是 BRAVE_SEARCH_API_KEY，放在 ~/.hermes/.env。

看起来很简单，把 key 从旧配置里复制过来就行。实际操作时需要先提取 key：

# 从 OpenClaw 配置中提取 key
grep apiKey ~/.openclaw/openclaw.json

然后写入 Hermes 环境变量：

echo 'BRAVE_SEARCH_API_KEY=<你的key>' >> ~/.hermes/.env

这里也有一个教训：写入配置时一定要校验完整性。写进去的值不等于完整的值，改完记得验证一下。

修好之后验证一下：

hermes doctor | grep web
# 输出 ✓ web 就说明搜索可用了

坑二：飞书审批按钮，点了没反应

这个坑最隐蔽，排查时间最长。

Hermes 执行敏感命令（写文件、网络请求等）时会弹出审批卡片，有「Allow Once」「Session」「Always」「Deny」四个按钮。但在飞书里点「Allow Once」，命令照旧超时被拦截，仿佛没点过一样。

反复试了好几次，每次都一样。就是下面这个界面，点「Allow Once」一点反应都没有：

最后去翻日志，发现了一条关键线索：

WARNING [Feishu] Unauthorized approval click by ou_xxxxxx

每次点击都被判定为「未授权」。跟踪源码发现，审批卡片的点击校验会检查操作者的 open_id 是否在授权列表中。而这个列表来源于环境变量 FEISHU_ALLOWED_USERS，当时是空的。

也就是说，虽然我是 bot 的主人，但因为没把自己的 open_id 加进授权列表，系统默认拒绝所有人的审批操作。

OpenClaw 里这个逻辑不一样，命令可以直接跑。Hermes 加了这层安全机制，但初始化时没有自动把当前用户加进去。配置了 FEISHU_GROUP_POLICY=allowlist（默认值）但没有配置 FEISHU_ALLOWED_USERS，就变成了「所有人都被拒绝」。

修复方法很简单：

# 在 ~/.hermes/.env 中添加
echo 'FEISHU_ALLOWED_USERS=ou_<你的open_id>' >> ~/.hermes/.env

# 重启 gateway 生效
hermes gateway restart

重启后审批按钮立刻生效了。

安全机制本身没问题，但配置缺省时用户完全无感，这是最坑的地方。

坑三：图片识别，视觉模型要重新配

OpenClaw 里 GLM 模型可以直接识别图片，迁移到 Hermes 后这个能力消失了。

第一反应是给主模型设置 supports_vision: true，让图片直接发给 GLM-5。结果 API 返回 429 错误：当前套餐不包含 GLM-5V-Turbo 视觉模型。回头去看 OpenClaw 的原始配置，才发现它用的视觉模型是 glm-4.6v，不是主模型 GLM-5。OpenClaw 有个独立的  配置段，专门指定视觉模型。

在 Hermes 里，视觉模型走的是 auxiliary.vision 配置段。需要在 ~/.hermes/config.yaml 中配置：

auxiliary:
  vision:
    provider: zai
    model: glm-4.6v
    timeout: 120

本以为这就完了，结果调用还是报 401 认证失败。

又是一轮源码追踪。发现 Hermes 对 zai 的视觉调用有特殊逻辑：它会尝试两个标准端点（open.bigmodel.cn 和 api.z.ai/api/paas/v4），但我用的是智谱国际版 Coding 套餐，API 端点是 api.z.ai/api/coding/paas/v4，这个 coding 端点不在默认列表里。

最终在源码的 zai_openai_urls 列表里加上了 coding 端点，重启后调用成功。GLM-4.6V 准确识别了飞书截图里的所有内容，包括界面元素、文字和交互逻辑。

还有一个小细节：glm-4.6v 调用时不能传 max_tokens 参数，否则报错码 1210。Hermes 源码已经针对视觉模型做了跳过处理，但如果自己手动调 API 要注意这个。

迁移后新增的能力

踩完这三个坑，基本的迁移算完成了。但 Hermes 也带来了 OpenClaw 没有的新能力——在飞书文档上直接运行 Agent。

Hermes 的飞书集成支持监听文档评论、读取文档内容、自动回复评论线程。这意味着可以在飞书文档的上下文中直接跑 AI Agent，不用切到聊天窗口。对飞书重度用户来说，这是个实打实的效率提升。

另外前面提到的 Playbook 到 Skill 的转换，虽然迁移成本不小，但 Hermes 的 skill 体系更结构化——每个 skill 是独立的目录，包含指令文件、脚本、模板和参考文档，比 OpenClaw 的 .md 路由方式更易维护和复用。

最后

迁移的核心经验就一句话：不要指望自动迁移，逐项验证每个能力。

排查问题有三板斧：hermes doctor 检查整体健康状态，hermes logs 看错误日志，实在不行直接看源码。两个框架都是开源的，遇到配置问题跟踪源码比猜配置靠谱得多。

每次改完配置记得重启 gateway：

hermes gateway restart

很多变更需要重启才生效。别问我怎么知道的。

迁移不是搬家，是重建。文件搬过来只是第一步，让每个能力在新环境里跑起来才是真正的迁移。

如果你也在做类似的迁移，或者对 Hermes Agent 有兴趣，欢迎留言讨论。