Claude Code / Hermes → OpenClaw 2026：使用 openclaw migrate 在 Mac mini M4 上完成迁移

OpenClaw v2026.4.26（2026年4月28日发布）带来了许多开发者期待已久的功能：openclaw migrate——一条命令就能将你在 Claude Code 或 Hermes 中积累的 AI 编程智能体配置完整导入 OpenClaw。如果你已经在 Claude Code 或 Hermes 中搭建了 MCP 服务器连接、自定义技能和工作流调优，希望无缝迁移到 OpenClaw 而无需逐件手动重建，本文将在 VpsGona Mac mini M4 节点上带你走完完整流程——包括哪些内容自动迁移、哪些需要手动处理，以及六个最常见迁移后问题的修复方法。

2026 年开发者从 Claude Code 和 Hermes 迁移到 OpenClaw 的原因

2026 年初迁移趋势加速，原因是具体的产品差距，而非营销。理解这些差距，有助于你判断迁移是否适合自己的工作流。

原因一：原生多智能体编排，无需插件变通。Claude Code 的多智能体支持需要各种变通，且仅限于 Anthropic 托管的模型路由。OpenClaw 的原生多智能体框架（ClawHub）允许编排共享 Memory-Wiki 状态层的独立智能体进程，支持任何模型提供商。并行运行研究、代码审查和测试生成智能体的团队，普遍认为 ClawHub 架构在管理上比 Claude Code 简单得多。

原因二：OpenClaw 的 OTEL 可观测性达到生产级别。自 v2026.4.25 起，OpenClaw 为每次模型调用、工具调用和内存访问发出结构化遥测数据。Claude Code 和 Hermes 均缺乏等效的结构化可观测性。需要 Token 成本归因、工具循环检测和内存压力告警的团队——尤其是运行无人值守的夜间自主智能体的团队——在其他工具中找不到对标功能。

原因三：提供商中立，内置 Cerebras 支持。OpenClaw v2026.4.26 新增了 Cerebras 作为内置提供商，加入 OpenAI、Anthropic、Gemini、DeepSeek 和本地 Ollama 模型的行列。Claude Code 在结构上与 Anthropic API 深度绑定。Hermes 有提供商灵活性，但插件 SDK 的成熟度不及 OpenClaw v2026 版本。如果你运行混合提供商工作流，OpenClaw 的插件清单架构可以跨提供商处理模型 ID 规范化，无需自定义配置。

openclaw migrate 在 v2026.4.26 中实际做了什么

openclaw migrate 命令对源工具的配置目录进行结构化扫描，提取兼容设置，并将其转换为 OpenClaw 的配置格式写入。它不会复制对话历史或会话日志——只迁移配置、能力定义和连接元数据。

迁移过程分三个阶段：

1. 发现阶段：OpenClaw 扫描源配置目录（Claude Code 为 ~/.claude/，Hermes 为 ~/.hermes/），检测已安装的 MCP 服务器、自定义技能/工具、API 密钥引用和提供商配置。
2. 转换阶段：每个检测到的条目映射到其 OpenClaw 等效项。MCP 服务器定义以 OpenClaw 的插件清单格式重新表达，API 密钥环境变量名称被创建别名，自定义工具定义被包装进 OpenClaw 的技能模式（skill schema）中。
3. 报告阶段：将 JSON 迁移报告写入 ~/.openclaw/migrate-report.json，列出每个成功迁移的条目、每个部分迁移（需要手动补全）的条目，以及每个无法迁移（格式不兼容或无 OpenClaw 等效项）的条目。

配置项	从 Claude Code 迁移	从 Hermes 迁移	说明
MCP 服务器端点定义	✓ 自动	✓ 自动	连接 URI 和认证头信息保留
自定义技能/工具定义	✓ 自动	✓ 自动	包装进 OpenClaw 技能模式；迁移后请逐一测试
API 密钥环境变量引用	✓ 自动创建别名	✓ 自动创建别名	只读取变量名，不读取实际密钥值；别名写入 .env
系统提示自定义	⚠ 部分（需审查）	⚠ 部分（需审查）	操作者身份格式在不同工具间有差异
模型提供商配置	⚠ 部分（仅 Anthropic）	✓ 自动（多提供商）	Claude Code 中的非 Anthropic 提供商无法迁移
记忆/知识库内容	✗ 不迁移	✗ 不迁移	需手动重新摄入 OpenClaw Memory-Wiki
对话/会话历史	✗ 不迁移	✗ 不迁移	设计决策——OpenClaw 会话格式不兼容
TaskFlow/Webhook 定义	✗ 不适用（Claude Code 无此功能）	⚠ 部分	Hermes 工作流定义需手动映射到 TaskFlows

迁移前检查清单：执行命令前必须核查的 7 项

在没有充分准备的情况下运行 openclaw migrate，是大多数迁移后问题的根源。在执行迁移命令前，请完成以下所有七项核查。

1. 确认 OpenClaw 版本 ≥ 2026.4.26。migrate 子命令在更早版本中不存在。使用 openclaw --version 检查。通过 npx openclaw@latest update 或在智能体内执行 /update 进行更新。
2. 备份源工具的配置目录。执行 cp -r ~/.claude/ ~/claude-backup-$(date +%Y%m%d)/（Claude Code）或 Hermes 的等效命令。迁移命令只读，但有一个带日期的备份能防止意外情况时的慌乱。
3. 列出所有活跃的 MCP 服务器。在 Claude Code 内执行 /mcp，记录所有已连接 MCP 服务器的名称和连接类型。稍后你将用这份清单核查迁移报告的覆盖情况。
4. 记录你的自定义系统提示修改。如果你修改了操作者身份、角色指令或安全覆盖，将这些内容复制到一个纯文本文件中。这些是迁移后最有可能需要手动审查的条目。
5. 确认 Mac mini M4 节点上 Node.js ≥ 20。migrate 使用 Node 原生 fetch API，需要 Node 20+。执行 node --version 验证。
6. 记录当前使用的 API 提供商。如果 Hermes 配置了多个提供商（如 OpenAI + Gemini + Cerebras），迁移前确认它们都在 OpenClaw 的内置提供商列表中。缺失的提供商会在报告中显示为 "manual-required"。
7. 确保 Mac mini M4 节点有足够磁盘空间。迁移过程将报告和转换后的配置文件写入 ~/.openclaw/。对大多数配置来说，500MB 可用空间绰绰有余。

分步操作：在 Mac mini M4 上从 Claude Code 迁移

以下步骤假设你已有一个活跃的 VpsGona Mac mini M4 会话，且 Claude Code 和 OpenClaw v2026.4.26+ 均已安装。SSH 连接到你的节点后，按顺序执行以下命令：

1. 验证两个工具均存在且版本正确：

   openclaw --version # 必须 ≥ 2026.4.26 claude --version # 确认 Claude Code 安装存在

2. 执行迁移命令，指向 Claude Code：

   openclaw migrate --from claude-code

   OpenClaw 会自动检测 ~/.claude/。如果你的 Claude Code 配置不在默认位置，使用 --source 参数明确指定：

   openclaw migrate --from claude-code --source /自定义路径/.claude/

3. 观察迁移输出。CLI 实时打印每个发现的条目。前缀 ✓ 表示迁移成功，⚠ 表示需要审查，✗ 表示无法迁移。典型的 Claude Code 迁移输出如下：

   Discovered: 8 MCP servers, 12 custom tools, 3 system prompt blocks, 1 provider config ✓ MCP server: filesystem-mcp → migrated ✓ MCP server: github-mcp → migrated ✓ MCP server: brave-search-mcp → migrated ⚠ System prompt block 'persona' → manual-required (format differs) ⚠ Provider: anthropic → partial (only Anthropic models available in source) ✗ Memory content → not migrated (re-ingest manually) Migration complete. Report: ~/.openclaw/migrate-report.json

4. 查看完整迁移报告：

   cat ~/.openclaw/migrate-report.json | python3 -m json.tool | head -80

5. 启动 OpenClaw 并验证 MCP 连接：

   openclaw start /mcp status

   每个已迁移的 MCP 服务器应显示绿色已连接状态。如有未连接的，参见下方排错章节。

分步操作：从 Hermes 迁移到 OpenClaw

Hermes 迁移遵循相同流程，但使用不同的 --from 参数，并有几个 Hermes 特有的注意事项。Hermes 默认将配置存储在 ~/.hermes/，使用 YAML 配置格式，OpenClaw 的迁移工具可以直接读取。

1. 执行 Hermes 迁移：

   openclaw migrate --from hermes

   对于 Hermes 工作区（项目级别的配置），指定工作区目录：

   openclaw migrate --from hermes --source /path/to/hermes-workspace/

2. 手动处理 Hermes 工作流定义。Hermes 使用的"工作流"构造部分映射到 OpenClaw 的 TaskFlows。迁移工具可以转换触发器和步骤结构，但无法自动复制条件分支逻辑。迁移后，在 OpenClaw 的 TaskFlow 编辑器中打开每个标记的工作流，手动验证分支条件是否正确表达。
3. 重新配置多提供商设置。如果你在 Hermes 中使用了多个模型提供商，验证每个提供商在 OpenClaw 的设置中均处于激活状态：

   openclaw config list-providers

   添加缺失的提供商：

   openclaw config add-provider cerebras --api-key $CEREBRAS_API_KEY

4. 重新摄入 Memory-Wiki 内容。Hermes 的记忆内容必须重新摄入 OpenClaw 的 Memory-Wiki。小型知识库（少于 50 份文档），使用 /learn 命令交互式摄入。更大的知识库使用批量摄入 API：

   openclaw memory ingest --dir /path/to/hermes/knowledge/ --format markdown

迁移覆盖范围：自动迁移 vs 手动处理

运行迁移命令并查看报告后，使用以下检查表确认没有遗漏关键内容：

条目类别	自动迁移？	需要的手动操作
MCP 服务器端点和认证	✓ 是	连接成功则无需操作；令牌过期则重新认证
自定义工具/技能定义	✓ 是	模式转换后手动运行每个工具验证行为
API 密钥环境变量别名	✓ 是（仅别名）	确认实际密钥在 ~/.openclaw/.env 或系统环境变量中
系统提示操作者身份	⚠ 部分	按 OpenClaw 的操作者格式审查和重写
模型提供商配置	⚠ 部分	Claude Code 迁移时手动添加非 Anthropic 提供商
Hermes 工作流条件	⚠ 部分	手动将条件分支转换为 TaskFlow 模式
记忆/知识库内容	✗ 否	通过 /learn 或批量摄入命令重新摄入所有文档
对话历史	✗ 否	无需操作——历史记录是工具特有的，不可移植
Matrix E2EE 配置（v2026.4.26 新功能）	✗ 不适用（全新功能）	从零开始配置：openclaw security matrix --setup

迁移后常见问题排查：6 个错误及修复方法

以下是首次运行 openclaw migrate 后 OpenClaw 社区中频繁出现的报错及解决方案。

问题一：迁移后 MCP 服务器显示"未连接"。最常见原因是认证令牌过期。使用 OAuth 或 Bearer Token 的 MCP 服务器存储的是令牌的引用而非令牌值本身——令牌会过期。解决方案：在 OpenClaw 控制面板中打开该 MCP 服务器的认证设置，重新进行认证。

问题二：openclaw migrate: source directory not found。如果你使用了非标准安装方式，Claude Code 可能不在默认位置。执行 find ~ -name ".claude" -type d 2>/dev/null 定位配置目录，然后用 --source 参数明确指定路径。

问题三：调用自定义工具时出现 schema validation error。迁移工具将工具包装进 OpenClaw 技能模式，但某些工具的参数类型没有精确对应项。检查 ~/.openclaw/skills/ 中该工具的参数定义，将类型声明与 OpenClaw 的模式对齐（string、number、boolean、array、object）。

问题四：迁移后启动挂起（v2026.4.26 已知问题）。部分用户在更新到 v2026.4.26 后报告启动延迟，尤其是配置了大量 MCP 服务器时。这是已知问题，连接初始化是同步的。临时解决方案：在 openclaw.config.js 中暂时禁用非必要 MCP 服务器，等启动完成后再逐步重新启用。

问题五：ENOENT: no such file or directory, open '~/.openclaw/.env'。迁移工具假设 .env 文件已存在。手动创建并填入你的实际密钥：

touch ~/.openclaw/.env echo "ANTHROPIC_API_KEY=你的密钥" >> ~/.openclaw/.env echo "OPENAI_API_KEY=你的密钥" >> ~/.openclaw/.env

问题六：迁移后 Ollama 连接失败。OpenClaw v2026.4.26 专门改进了 Qwen 和 Gemma 4 模型的 Ollama 可靠性。如果 Ollama 在 Hermes 中能正常工作但在 OpenClaw 中失败，检查你运行的是否是 Ollama 0.22.0 或更高版本——社区报告确认这个版本解决了与更新检索路径的兼容性问题：

ollama --version # 应为 ≥ 0.22.0 ollama serve # 确认 Ollama 在 OpenClaw 启动前已运行

在 Mac mini M4 上优化已迁移的 OpenClaw 配置

迁移稳定、所有 MCP 服务器正常连接后，以下四项优化对 Mac mini M4 部署特别有价值：

• 根据实际使用的模型设置 maxContextTokens。迁移后的配置继承了通用的上下文窗口大小。在拥有 16GB 统一内存的 Mac mini M4 上，Claude 3.7 Sonnet 的 200K 上下文窗口内存消耗较大。对于典型的编码任务，在 openclaw.config.js 中将 maxContextTokens 设置为 32768，可显著降低内存压力，同时覆盖几乎所有真实编码会话。
• 启用新的 JSON5 待定更改差异面板。这是 v2026.4.26 的新功能，在智能体提交文件更改前展示结构化差异。在通过 SSH 远程管理 Mac mini M4 节点、无法实时可视化检查工作目录的场景下，这个面板特别有价值：

  // openclaw.config.js 中 ui: { pendingChangesDiff: true, diffFormat: 'json5' }

• 为速度敏感型任务配置 Cerebras 提供商。Cerebras 现在是 v2026.4.26 的内置提供商。对于响应延迟比输出长度更重要的任务——快速代码解释、类型注解建议、测试用例生成——Cerebras 模型在相似质量水平上提供比 Anthropic 或 OpenAI 明显更低的首 Token 到达时间。
• 为安全的远程会话配置 Matrix E2EE。这是 Claude Code 和 Hermes 均不具备的全新功能。在 VpsGona 节点上运行 OpenClaw 时，所有数据已通过 SSH 传输，但添加 Matrix E2EE 在应用层增加了端到端加密——特别适合智能体处理含敏感凭据代码的场景：

  openclaw security matrix --setup

为何 VpsGona Mac mini M4 是 OpenClaw 迁移的理想目标环境

迁移到 OpenClaw 是一次配置变更；在哪里运行 OpenClaw，决定了迁移能否发挥完整价值。对于原本在个人笔记本或台式机上运行 Claude Code 或 Hermes 的开发者，迁移到 VpsGona Mac mini M4 节点上的 OpenClaw，在几个具体方面改变了局面。

首先，Mac mini M4 的 Apple Silicon 架构与 Claude Code 用户积累的每一个 macOS 专用 MCP 服务器和工具天然兼容。文件系统访问、Xcode 集成、通过 AppleScript 或 Shortcuts 实现的 macOS 自动化，以及基于 CoreML 的本地模型推理，全部在 M4 芯片上如预期运行——没有 x86 仿真的兼容层开销。当你迁移 MCP 服务器配置时，它们落入的是与设计目标完全相同的 OS 和芯片架构环境。

其次，VpsGona 无最低承诺的租用模式与 OpenClaw 的使用模式天然契合。OpenClaw 最强大的功能——通过 ClawHub 的多智能体编排、OTEL 可观测性、无人值守的夜间自主智能体——在专属节点上持续运行时最有价值，而不是在个人电脑上间歇使用。按项目周期租用专门运行 OpenClaw 工作负载的 Mac mini M4 节点，成本是独立服务器方案的一小部分，同时提供原生 Apple Silicon 性能。新的 OTEL 集成还意味着你可以将每小时的计算成本归因到具体的智能体任务，把 VpsGona 的账单变成 AI 计算实际投入的可审计记录。查看当前节点配置详情，请访问 VpsGona 定价页；OpenClaw 环境配置说明，请参见 帮助文档。