sidebar_position: 10 title: “Migrate from OpenClaw” description: “Complete guide to migrating your OpenClaw / Clawdbot setup to Hermes Agent — what gets migrated, how config maps, and what to check after.”

从 OpenClaw 迁移

hermes claw migrate 命令可将您现有的 OpenClaw（或旧版的 Clawdbot/Moldbot）配置导入 Hermes。本指南将详细说明哪些内容会被迁移、配置键的对应关系，以及迁移完成后需要验证的事项。

::note 如果您是从 Claude Code 或 OpenAI Codex CLI 过渡而来？请使用 hermes import-agent 命令。

::

::tip 如果您的 OpenClaw 配置使用了多个提供商，可使用 hermes setup --portal 将其整合为单一的 OAuth 认证——只需一次登录即可使用 300 多种模型以及工具网关。详情请参阅 Nous Portal。

::

快速入门

# Preview then migrate (always shows a preview first, then asks to confirm)
hermes claw migrate

# Preview only, no changes
hermes claw migrate --dry-run

# Full migration including API keys, skip confirmation
hermes claw migrate --preset full --migrate-secrets --yes

在执行任何更改之前，该迁移工具总会先完整预览即将导入的内容。请仔细查看列表，确认无误后再继续操作。

默认从 ~/.openclaw/ 目录读取数据。系统会自动识别旧的 ~/.clawdbot/ 或 ~/.moltbot/ 目录，旧的配置文件名（如 clawdbot.json、moltbot.json）也是如此。

选项

将被迁移的内容

人物设定、记忆内容及指令信息

作为备用路径，还会检查 workspace.default/ 和 workspace-main/ 中的文件（在最新版本中，OpenClaw 将 workspace/ 更名为 workspace-main/，而在多智能体环境中则使用 workspace-{agentId} 作为路径）。

技能（4个来源）

模型与提供者配置

Agent 行为表现

会话生命周期

空闲计时器和每日重置计时器不会被导入：Hermes 对话会一直保留，直到用户明确发出 /new 或 /reset 命令。而高级会话设置（如身份关联、线程绑定、维护选项、作用域及发送策略）则会被存档以供后续参考。

MCP 服务器

文本转语音（TTS）

TTS 设置会从 两个 OpenClaw 配置位置读取，其优先级如下：

1. messages.tts.providers.{provider}.*（标准配置位置）
2. 顶层配置的 talk.providers.{provider}.*（备用位置）
3. 旧版的扁平键格式 messages.tts.{provider}.*（最旧格式）

消息传递平台

其他配置项

归档配置（Hermes 中无直接对应项）

此类配置会被保存至 ~/.hermes/migration/openclaw/<时间戳>/archive/ 目录，以便人工查看：

API 密钥解析

当启用 --migrate-secrets 参数时，API 密钥会按优先级从四个来源中收集：

1. 配置值 — models.providers.*.apiKey 以及 openclaw.json 中的 TTS 提供商密钥
2. 环境文件 — ~/.openclaw/.env（包含如 OPENROUTER_API_KEY、ANTHROPIC_API_KEY 等键值）
3. 配置环境子对象 — openclaw.json → "env" 或 "env"."vars"（部分配置会将密钥存储于此，而非单独的 .env 文件中）
4. 认证配置文件 — ~/.openclaw/agents/main/agent/auth-profiles.json（用于存储每个智能体的凭证）

配置值的优先级最高，后续的配置来源将填补剩余的空缺。

支持的密钥类型

OPENROUTER_API_KEY、OPENAI_API_KEY、ANTHROPIC_API_KEY、DEEPSEEK_API_KEY、GEMINI_API_KEY、ZAI_API_KEY、MINIMAX_API_KEY、ELEVENLABS_API_KEY、TELEGRAM_BOT_TOKEN、VOICE_TOOLS_OPENAI_KEY

不在此列表中的密钥将不会被复制。

SecretRef 处理方式

OpenClaw 中用于存储令牌和 API 密钥的配置值可采用三种格式：

// Plain string
"channels": { "telegram": { "botToken": "123456:ABC-DEF..." } }

// Environment template
"channels": { "telegram": { "botToken": "${TELEGRAM_BOT_TOKEN}" } }

// SecretRef object
"channels": { "telegram": { "botToken": { "source": "env", "id": "TELEGRAM_BOT_TOKEN" } } }

此次迁移可处理这三种格式的配置。对于源类型为 env 的环境模板和 SecretRef 对象，系统会从 ~/.openclaw/.env 文件以及 openclaw.json 中的环境子对象中查找对应值。而源类型为 file 或 exec 的 SecretRef 对象则无法自动完成解析——系统会针对这类对象发出警告，相关值必须通过 hermes config set 命令手动添加到 Hermes 中。

迁移完成后

1. 查看迁移报告——迁移完成后会生成该报告，其中列明了已迁移、跳过以及存在冲突的项的数量。

2. 检查归档文件——位于 ~/.hermes/migration/openclaw/<timestamp>/archive/ 目录中的所有文件都需要人工处理。

3. 启动新会话——已导入的技能和内存条目仅在新建的会话中生效，当前会话不受影响。

4. 验证 API 密钥——运行 hermes status 命令以检查服务提供方的身份认证状态。

5. 测试消息功能——如果已迁移平台令牌，需重启网关：systemctl --user restart hermes-gateway

6. 查看会话归档文件——检查归档后的高级设置；出于设计考虑，空闲计时器和每日重置计时器不会被导入。

7. 重新配对 WhatsApp——WhatsApp 使用二维码配对方式（Baileys 协议），而非令牌迁移机制。需运行 hermes whatsapp 命令进行配对。

8. 清理归档文件——确认所有功能正常后，运行 hermes claw cleanup 命令将剩余的 OpenClaw 目录重命名为 .pre-migration/（以避免状态混淆）。

故障排除

“未找到 OpenClaw 目录”

迁移过程会依次检查 ~/.openclaw/、~/.clawdbot/ 和 ~/.moltbot/ 这三个目录。如果您的安装路径不在这些位置，请使用 --source /path/to/your/openclaw 参数指定路径。

“未找到提供者 API 密钥”

根据 OpenClaw 的版本不同，密钥可能存储在多个位置：openclaw.json 文件中 models.providers.*.apiKey 字段内、~/.openclaw/.env 文件中、openclaw.json 的 "env" 子对象中，或是 agents/main/agent/auth-profiles.json 文件中。迁移工具会逐一检查这四个位置。如果密钥使用了 source: "file" 或 source: "exec" 类型的 SecretRefs，系统将无法自动解析这些密钥——需要通过 hermes config set 命令手动添加。

迁移后技能未显示

导入的技能会存储在 ~/.hermes/skills/openclaw-imports/ 目录下。需要启动新会话才能让这些技能生效，或者运行 /skills 命令来确认它们已被加载。

TTS 语音未同步迁移

OpenClaw 会将 TTS 相关设置存储在两个位置：messages.tts.providers.* 文件以及顶层的 talk 配置文件中。迁移过程会同时检查这两个位置。如果您的声音 ID 是通过 OpenClaw 用户界面设置的（且存储在其他路径），则可能需要手动设置：hermes config set tts.elevenlabs.voice_id YOUR_VOICE_ID。