跳到主要内容

从 OpenClaw 迁移

hermes claw migrate 将你的 OpenClaw（或遗留 Clawdbot/Moldbot）设置导入 Hermes。本指南涵盖确切迁移内容、配置键映射以及迁移后要验证的内容。

快速开始​

# 预览然后迁移（始终先显示预览，然后询问确认）
hermes claw migrate

# 仅预览，不做任何更改
hermes claw migrate --dry-run

# 完整迁移包括 API 密钥，跳过确认
hermes claw migrate --preset full --yes

迁移始终在做任何更改之前显示将要导入内容的完整预览。检查列表，然后确认继续。

默认从 ~/.openclaw/ 读取。遗留的 ~/.clawdbot/ 或 ~/.moltbot/ 目录被自动检测。同样用于遗留配置文件名（clawdbot.json、moltbot.json）。

选项​

| 选项 | 描述 | | |--------|-------------| | | --dry-run | 仅预览 — 显示将要迁移的内容后停止。 | | --preset <name> | full（默认，包含密钥）或 user-data（排除 API 密钥）。 | | --overwrite | 冲突时覆盖现有 Hermes 文件（默认：跳过）。 | | --migrate-secrets | 包含 API 密钥（--preset full 时默认）。 | | --source <path> | 自定义 OpenClaw 目录。 | | --workspace-target <path> | 放置 AGENTS.md 的位置。 | | --skill-conflict <mode> | skip（默认）、overwrite 或 rename。 | | --yes | 跳过预览后的确认提示。 |

迁移内容​

人格、记忆和指令​

| 内容 | OpenClaw 源 | Hermes 目标 | 说明 | | |------|----------------|-------------------|-------| | | 人格 | workspace/SOUL.md | ~/.hermes/SOUL.md | 直接复制 | | | 工作区指令 | workspace/AGENTS.md | --workspace-target 中的 AGENTS.md | 需要 --workspace-target 标志 | | | 长期记忆 | workspace/MEMORY.md | ~/.hermes/memories/MEMORY.md | 解析为条目，与现有合并，去重。使用 § 分隔符。 | | | 用户档案 | workspace/USER.md | ~/.hermes/memories/USER.md | 与记忆相同的条目合并逻辑。 | | | 每日记忆文件 | workspace/memory/*.md | ~/.hermes/memories/MEMORY.md | 所有每日文件合并到主记忆。 | |

工作区文件也在 workspace.default/ 和 workspace-main/ 检查作为后备路径（OpenClaw 在最新版本中将 workspace/ 重命名为 workspace-main/，并对多 agent 设置使用 workspace-{agentId}）。

技能（4 个来源）​

| 来源 | OpenClaw 位置 | Hermes 目标 | | |--------|------------------|-------------------| | | 工作区技能 | workspace/skills/ | ~/.hermes/skills/openclaw-imports/ | | | 托管/共享技能 | ~/.openclaw/skills/ | ~/.hermes/skills/openclaw-imports/ | | | 个人跨项目 | ~/.agents/skills/ | ~/.hermes/skills/openclaw-imports/ | | | 项目级共享 | workspace/.agents/skills/ | ~/.hermes/skills/openclaw-imports/ | |

技能冲突由 --skill-conflict 处理：skip 保留现有 Hermes 技能，overwrite 替换它，rename 创建 -imported 副本。

模型和提供商配置​

| 内容 | OpenClaw 配置路径 | Hermes 目标 | 说明 | | |------|---------------------|-------------------|-------| | | 默认模型 | agents.defaults.model | config.yaml → model | 可以是字符串或 {primary, fallbacks} 对象 | | 自定义提供商 | models.providers.* | config.yaml → custom_providers | 映射 baseUrl、apiType/api — 处理短格式（"openai"、"anthropic"）和连字符格式（"openai-completions"、"anthropic-messages"、"google-generative-ai"）值 | | 提供商 API 密钥 | models.providers.*.apiKey | ~/.hermes/.env | 需要 --migrate-secrets。见下面的 API 密钥解析。 |

Agent 行为​

| 内容 | OpenClaw 配置路径 | Hermes 配置路径 | 映射 | | |------|---------------------|-------------------|---------| | | 最大轮次 | agents.defaults.timeoutSeconds | agent.max_turns | timeoutSeconds / 10，上限为 200 | | 详细模式 | agents.defaults.verboseDefault | agent.verbose | "off" / "on" / "full" | | 推理努力 | agents.defaults.thinkingDefault | agent.reasoning_effort | "always"/"high"/"xhigh" → "high"，"auto"/"medium"/"adaptive" → "medium"，"off"/"low"/"none"/"minimal" → "low" | | 压缩 | agents.defaults.compaction.mode | compression.enabled | "off" → false，其他 → true | | 压缩模型 | agents.defaults.compaction.model | compression.summary_model | 直接字符串复制 | | 人类延迟 | agents.defaults.humanDelay.mode | human_delay.mode | "natural" / "custom" / "off" | | 人类延迟时序 | agents.defaults.humanDelay.minMs / .maxMs | human_delay.min_ms / .max_ms | 直接复制 | | 时区 | agents.defaults.userTimezone | timezone | 直接字符串复制 | | 执行超时 | tools.exec.timeoutSec | terminal.timeout | 直接复制（字段是 timeoutSec，不是 timeout） | | Docker 沙箱 | agents.defaults.sandbox.backend | terminal.backend | "docker" → "docker" | | Docker 镜像 | agents.defaults.sandbox.docker.image | terminal.docker_image | 直接复制 |

会话重置策略​

| OpenClaw 配置路径 | Hermes 配置路径 | 说明 | | |---------------------|-------------------|-------| | | session.reset.mode | session_reset.mode | "daily"、"idle" 或两者 | | session.reset.atHour | session_reset.at_hour | 每日重置的小时（0–23） | | session.reset.idleMinutes | session_reset.idle_minutes | 不活跃分钟数 |

注意：OpenClaw 也有 session.resetTriggers（简单字符串数组如 ["daily", "idle"]）。如果不存在结构化 session.reset，迁移会回退到从 resetTriggers 推断。

MCP 服务器​

| OpenClaw 字段 | Hermes 字段 | 说明 | | |----------------|-------------|-------| | | mcp.servers.*.command | mcp_servers.*.command | Stdio 传输 | | mcp.servers.*.args | mcp_servers.*.args | | | mcp.servers.*.env | mcp_servers.*.env | | | mcp.servers.*.cwd | mcp_servers.*.cwd | | | mcp.servers.*.url | mcp_servers.*.url | HTTP/SSE 传输 | | mcp.servers.*.tools.include | mcp_servers.*.tools.include | 工具过滤 | | mcp.servers.*.tools.exclude | mcp_servers.*.tools.exclude | |

TTS（文本转语音）​

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

  1. messages.tts.providers.{provider}.*（规范位置）
  2. 顶级 talk.providers.{provider}.*（后备）
  3. 遗留平键 messages.tts.{provider}.*（最旧格式）

| 内容 | Hermes 目标 | | |------|-------------------| | | 提供商名称 | config.yaml → tts.provider | | | ElevenLabs 语音 ID | config.yaml → tts.elevenlabs.voice_id | | | ElevenLabs 模型 ID | config.yaml → tts.elevenlabs.model_id | | | OpenAI 模型 | config.yaml → tts.openai.model | | | OpenAI 语音 | config.yaml → tts.openai.voice | | | Edge TTS 语音 | config.yaml → tts.edge.voice（OpenClaw 将 "edge" 重命名为 "microsoft" — 两者都被识别） | | | TTS 资产 | ~/.hermes/tts/（文件复制） | |

消息平台​

| 平台 | OpenClaw 配置路径 | Hermes .env 变量 | 说明 | | |----------|---------------------|----------------------|-------| | | Telegram | channels.telegram.botToken 或 .accounts.default.botToken | TELEGRAM_BOT_TOKEN | 令牌可以是字符串或 SecretRef。支持平铺和 accounts 布局。 | | Telegram | credentials/telegram-default-allowFrom.json | TELEGRAM_ALLOWED_USERS | 从 allowFrom[] 数组逗号连接 | | Discord | channels.discord.token 或 .accounts.default.token | DISCORD_BOT_TOKEN | | | Discord | channels.discord.allowFrom 或 .accounts.default.allowFrom | DISCORD_ALLOWED_USERS | | | Slack | channels.slack.botToken 或 .accounts.default.botToken | SLACK_BOT_TOKEN | | | Slack | channels.slack.appToken 或 .accounts.default.appToken | SLACK_APP_TOKEN | | | Slack | channels.slack.allowFrom 或 .accounts.default.allowFrom | SLACK_ALLOWED_USERS | | | WhatsApp | channels.whatsapp.allowFrom 或 .accounts.default.allowFrom | WHATSAPP_ALLOWED_USERS | 通过 Baileys QR 配对进行认证 — 迁移后需要重新配对 | | Signal | channels.signal.account 或 .accounts.default.account | SIGNAL_ACCOUNT | | | Signal | channels.signal.httpUrl 或 .accounts.default.httpUrl | SIGNAL_HTTP_URL | | | Signal | channels.signal.allowFrom 或 .accounts.default.allowFrom | SIGNAL_ALLOWED_USERS | | | Matrix | channels.matrix.accessToken 或 .accounts.default.accessToken | MATRIX_ACCESS_TOKEN | 使用 accessToken（不是 botToken） | | Mattermost | channels.mattermost.botToken 或 .accounts.default.botToken | MATTERMOST_BOT_TOKEN | |

其他配置​

| 内容 | OpenClaw 路径 | Hermes 路径 | 说明 | | |------|-------------|-------------|-------| | | 审批模式 | approvals.exec.mode | config.yaml → approvals.mode | "auto"→"off"、"always"→"manual"、"smart"→"smart" | | 命令白名单 | exec-approvals.json | config.yaml → command_allowlist | 模式合并并去重 | | 浏览器 CDP URL | browser.cdpUrl | config.yaml → browser.cdp_url | | | 浏览器无头 | browser.headless | config.yaml → browser.headless | | | Brave 搜索密钥 | tools.web.search.brave.apiKey | .env → BRAVE_API_KEY | 需要 --migrate-secrets | | Gateway 认证令牌 | gateway.auth.token | .env → HERMES_GATEWAY_TOKEN | 需要 --migrate-secrets | | 工作目录 | agents.defaults.workspace | .env → MESSAGING_CWD | |

已归档（无直接 Hermes 等效项）​

这些保存到 ~/.hermes/migration/openclaw/<timestamp>/archive/ 供手动审查：

| 内容 | 归档文件 | 如何在 Hermes 中重新创建 | | |------|-------------|--------------------------| | | IDENTITY.md | archive/workspace/IDENTITY.md | 合并到 SOUL.md | | | TOOLS.md | archive/workspace/TOOLS.md | Hermes 有内置工具指令 | | | HEARTBEAT.md | archive/workspace/HEARTBEAT.md | 使用 cron 任务进行定期任务 | | | BOOTSTRAP.md | archive/workspace/BOOTSTRAP.md | 使用上下文文件或技能 | | | Cron 任务 | archive/cron-config.json | 用 hermes cron create 重新创建 | | | 插件 | archive/plugins-config.json | 参见插件指南 | | | 钩子/webhook | archive/hooks-config.json | 使用 hermes webhook 或 gateway 钩子 | | | 记忆后端 | archive/memory-backend-config.json | 通过 hermes honcho 配置 | | | 技能注册表 | archive/skills-registry-config.json | 使用 hermes skills config | | | UI/身份 | archive/ui-identity-config.json | 使用 /skin 命令 | | | 日志记录 | archive/logging-diagnostics-config.json | 在 config.yaml 日志部分设置 | | | 多 agent 列表 | archive/agents-list.json | 使用 Hermes profiles | | | 频道绑定 | archive/bindings.json | 每个平台手动设置 | | | 复杂频道 | archive/channels-deep-config.json | 手动平台配置 | |

API 密钥解析​

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

  1. 配置值 — openclaw.json 中的 models.providers.*.apiKey 和 TTS 提供商密钥
  2. 环境文件 — ~/.openclaw/.env（如 OPENROUTER_API_KEY、ANTHROPIC_API_KEY 等的密钥）
  3. 配置 env 子对象 — openclaw.json → "env" 或 "env"."vars"（某些设置将密钥存储在这里而不是单独的 .env 文件）
  4. 认证配置文件 — ~/.openclaw/agents/main/agent/auth-profiles.json（每个 agent 的凭据）

配置值优先。每个后续来源填充任何剩余空白。

支持的密钥目标​

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" } } }

迁移解析所有三种格式。对于带有 source: "env" 的 env 模板和 SecretRef 对象，它在 ~/.openclaw/.env 和 openclaw.json env 子对象中查找值。带有 source: "file" 或 source: "exec" 的 SecretRef 对象无法自动解析 — 迁移会警告这些，这些值必须通过 hermes config set 手动添加到 Hermes。

迁移后​

  1. 检查迁移报告 — 完成后打印，包含迁移、跳过和冲突项目的计数。

  2. 审查归档文件 — ~/.hermes/migration/openclaw/<timestamp>/archive/ 中的任何内容都需要手动处理。

  3. 开始新会话 — 导入的技能和记忆条目在新会话中生效，不是在当前会话中。

  4. 验证 API 密钥 — 运行 hermes status 检查提供商认证。

  5. 测试消息传递 — 如果你迁移了平台令牌，重启 gateway：systemctl --user restart hermes-gateway

  6. 检查会话策略 — 验证 hermes config get session_reset 符合你的预期。

  7. 重新配对 WhatsApp — WhatsApp 使用 QR 码配对（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 UI 设置的（存储在不同路径），你可能需要手动设置：hermes config set tts.elevenlabs.voice_id YOUR_VOICE_ID。