如果你是 OpenClaw（或更早期的 Clawdbot / Moldbot）用户，Hermes Agent 提供了一条完整的迁移路径。这篇教程帮助你把现有的配置、记忆、技能和平台集成一次性搬到 Hermes。
前置准备
1. 安装 Hermes Agent
如果你还没装 Hermes，先执行官方一键安装脚本（支持 Linux / macOS / WSL2 / Termux）：
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
安装完成后重新加载 shell：
source ~/.bashrc # 或 source ~/.zshrc
Windows 用户请先安装 WSL2，再执行上述命令。
2. 确认 OpenClaw 目录存在
迁移工具会按以下顺序查找你的 OpenClaw 安装目录：
~/.openclaw/~/.clawdbot/（旧版本）~/.moltbot/（更早版本）
如果安装在其他位置，后续命令需要加 --source /your/path。
快速开始
Hermes 提供了一个 hermes claw migrate 命令来处理整个迁移过程。三种常用方式：
# 预览后确认迁移（推荐首次使用）
hermes claw migrate
# 仅预览，不做任何改动
hermes claw migrate --dry-run
# 全量迁移（含 API 密钥），跳过确认
hermes claw migrate --preset full --yes
建议第一次先用 --dry-run 看看会迁移什么，确认没问题再正式执行。
命令选项详解
| 选项 | 说明 |
|---|---|
--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（重命名为 -imported） |
--yes | 跳过预览后的确认提示 |
迁移内容详解
一、人设、记忆与指令
这是 OpenClaw 用户最核心的数据。迁移工具会自动处理格式转换和去重。
| 内容 | OpenClaw 路径 | Hermes 目标路径 | 说明 |
|---|---|---|---|
| 人设 | workspace/SOUL.md | ~/.hermes/SOUL.md | 直接复制 |
| 工作区指令 | workspace/AGENTS.md | 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/目录不存在，工具会依次检查workspace.default/和workspace-main/。
二、技能迁移
OpenClaw 的技能分散在四个位置，全部会被导入到 ~/.hermes/skills/openclaw-imports/：
| 来源 | 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— 用 OpenClaw 技能覆盖rename— 导入为-imported后缀副本
三、模型与 Provider 配置
| 内容 | OpenClaw 配置路径 | Hermes 目标 | 说明 |
|---|---|---|---|
| 默认模型 | agents.defaults.model | config.yaml → model | 支持字符串或 {primary, fallbacks} 对象 |
| 自定义 Provider | models.providers.* | config.yaml → custom_providers | 映射 baseUrl、apiType/api |
| Provider API 密钥 | models.providers.*.apiKey | ~/.hermes/.env | 需要 --migrate-secrets |
四、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 | 直接复制 |
| 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 | 空闲多少分钟后重置 |
旧版兼容：如果没有
session.reset，工具会从session.resetTriggers数组推断。
六、消息平台迁移
这是很多用户最关心的部分。迁移工具支持 7 个主流平台：
Telegram
| OpenClaw 路径 | Hermes 环境变量 | 说明 |
|---|---|---|
channels.telegram.botToken 或 .accounts.default.botToken | TELEGRAM_BOT_TOKEN | 支持字符串、环境模板和 SecretRef 三种格式 |
credentials/telegram-default-allowFrom.json | TELEGRAM_ALLOWED_USERS | 从 allowFrom[] 数组逗号拼接 |
Discord
| OpenClaw 路径 | Hermes 环境变量 |
|---|---|
channels.discord.token 或 .accounts.default.token | DISCORD_BOT_TOKEN |
channels.discord.allowFrom | DISCORD_ALLOWED_USERS |
Slack
| OpenClaw 路径 | Hermes 环境变量 |
|---|---|
channels.slack.botToken | SLACK_BOT_TOKEN |
channels.slack.appToken | SLACK_APP_TOKEN |
channels.slack.allowFrom | SLACK_ALLOWED_USERS |
| OpenClaw 路径 | Hermes 环境变量 | 说明 |
|---|---|---|
channels.whatsapp.allowFrom | WHATSAPP_ALLOWED_USERS | 注意：WhatsApp 使用 Baileys QR 码配对，迁移后需要重新扫码 |
Signal
| OpenClaw 路径 | Hermes 环境变量 |
|---|---|
channels.signal.account | SIGNAL_ACCOUNT |
channels.signal.httpUrl | SIGNAL_HTTP_URL |
channels.signal.allowFrom | SIGNAL_ALLOWED_USERS |
Matrix
| OpenClaw 路径 | Hermes 环境变量 | 说明 |
|---|---|---|
channels.matrix.accessToken | MATRIX_ACCESS_TOKEN | 注意是 accessToken，不是 botToken |
Mattermost
| OpenClaw 路径 | Hermes 环境变量 |
|---|---|
channels.mattermost.botToken | MATTERMOST_BOT_TOKEN |
七、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 配置：
messages.tts.providers.{provider}.*（标准位置）talk.providers.{provider}.*（回退）messages.tts.{provider}.*（最旧格式）
支持 ElevenLabs（voice_id、model_id）、OpenAI（model、voice）和 Edge TTS（voice）。
九、其他配置
| 内容 | OpenClaw 路径 | Hermes 路径 | 说明 |
|---|---|---|---|
| 审批模式 | approvals.exec.mode | config.yaml → approvals.mode | auto → off，always → manual，smart → smart |
| 命令白名单 | exec-approvals.json | config.yaml → command_allowlist | 合并去重 |
| 浏览器 CDP | browser.cdpUrl | config.yaml → browser.cdp_url | 直接复制 |
| 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 | 直接复制 |
API 密钥处理
当启用 --migrate-secrets 时，迁移工具从四个来源按优先级收集 API 密钥：
- 配置值 —
openclaw.json中的models.providers.*.apiKey和 TTS 密钥 - 环境文件 —
~/.openclaw/.env（如OPENROUTER_API_KEY、ANTHROPIC_API_KEY等） - 配置 env 子对象 —
openclaw.json中的"env"或"env"."vars"字段 - Auth 配置文件 —
~/.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 中 token 和 API 密钥可能有三种格式，迁移工具都能处理：
// 1. 纯字符串
{ "botToken": "123456:ABC-DEF..." }
// 2. 环境变量模板
{ "botToken": "${TELEGRAM_BOT_TOKEN}" }
// 3. SecretRef 对象
{ "botToken": { "source": "env", "id": "TELEGRAM_BOT_TOKEN" } }
对于 source: "file" 或 source: "exec" 类型的 SecretRef，无法自动解析，迁移工具会发出警告，需要手动通过 hermes config set 添加。
无法自动迁移的内容
以下内容没有直接的 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 | 使用 context 文件或 skills |
| Cron 任务 | archive/cron-config.json | 用 hermes cron create 重建 |
| 插件 | archive/plugins-config.json | 参考 Hermes 插件文档 |
| Hooks/Webhooks | archive/hooks-config.json | 使用 hermes webhook 或 gateway hooks |
| 记忆后端 | 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 的 logging 部分设置 |
| 多 Agent 列表 | archive/agents-list.json | 使用 Hermes profiles |
| 频道绑定 | archive/bindings.json | 手动配置各平台 |
| 复杂频道配置 | archive/channels-deep-config.json | 手动配置各平台 |
迁移后检查清单
完成迁移后，按以下步骤逐一确认：
1. 查看迁移报告
迁移完成后会打印摘要，包含已迁移、已跳过和有冲突的项目数量。
2. 检查归档文件
查看 ~/.hermes/migration/openclaw/<timestamp>/archive/ 目录，里面是需要手动处理的文件。
3. 开启新会话
导入的技能和记忆条目需要新会话才能生效。
4. 验证 API 密钥
hermes status
检查各 provider 的认证状态。
5. 测试消息平台
如果迁移了平台 token，重启 gateway：
systemctl --user restart hermes-gateway
6. 确认会话策略
hermes config get session_reset
7. 重新配对 WhatsApp
WhatsApp 使用 Baileys QR 码配对，不能通过 token 迁移。需要重新运行：
hermes whatsapp
8. 清理旧目录
一切确认无误后，归档 OpenClaw 旧目录：
hermes claw cleanup
这会将遗留的 OpenClaw 目录重命名为 .pre-migration/。
常见问题排查
"OpenClaw directory not found"
迁移工具默认检查 ~/.openclaw/、~/.clawdbot/、~/.moltbot/ 三个路径。如果你的安装在其他位置：
hermes claw migrate --source /path/to/your/openclaw
"No provider API keys found"
API 密钥可能分布在多个位置（取决于你的 OpenClaw 版本）：
openclaw.json中的models.providers.*.apiKey~/.openclaw/.envopenclaw.json的"env"子对象agents/main/agent/auth-profiles.json
迁移工具会检查所有四个位置。如果密钥使用了 source: "file" 或 source: "exec" 类型的 SecretRef，需要手动添加：
hermes config set providers.openrouter.api_key YOUR_KEY
技能迁移后不显示
导入的技能位于 ~/.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
小结
整个迁移流程可以概括为三步：
hermes claw migrate --dry-run— 先预览，心里有数hermes claw migrate --preset full— 正式迁移- 逐项检查 — 按清单确认每个模块
Hermes 的迁移工具覆盖面很广，大部分配置都能自动处理。少数不支持的项目会归档保存并给出提示，不会丢失数据。